NAS4Free / FreeBSD / BHyve Guide

[texneus]

Update Dec 15, 2017: I am pleased to state that the problem was actually a very simple one and after several weeks of testing I am confident that this is working 100%. The issue was that I had fairly aggressive power management settings enabled, with that relaxed all is well. When testing I also found a superior way for the TV drives to be accessed. Although the below does work, it seems to cause an abnormal amount of disk activity. I will publish a create a new guide and upload it here probably early next year.

Update Nov 28, 2017: I regret to announce this project has been abandoned for reasons stated in post 5 bellow. The instructions will remain here in case somebody still wants to give this a try. I remain hopeful that it can be made to work 100% so if somebody would like to work on this, by all means feel free!

(Part 1 of 2)

The goal of this guide is specifically to implement a SageTV server on NAS4Free, a FreeBSD based NAS OS. It's not that I have anything against unRAID, but the fact is I have been running NAS4Free for several years now and I do not wish to start over and nor do I want to loose the ZFS filesystem. The problem is that SageTV is unavailable for FreeBSD at this time. Furthermore, Docker is not currently an option on FreeBSD (Docker is present but listed as "experimental" and development appears to have been stalled for a while), so there is no way to natively run SageTV server on a FreeBSD system.

FreeBSD does have BHyve. BHyve is the FreeBSD native hypervisor that comes "baked in" to FreeBSD, which allows FreeBSD to run virtual machines "out of the box". A BHyve extension for NAS4Free is in the very early stages of development, but trials with it revealed a number of issues without a viable work around. None-the-less, BHyve can still be used if one looks "under the hood". The idea here is to use a BHyve virtual machine to run a Docker capable OS, which in turn hosts the SageTV Docker VM. On a kludge scale of 1-10, this is without a doubt an 11, but it does result in a fully functional and stable SageTV server on NAS4Free until better option(s) are available.

The following walk through will describe how to implement a BHyve virtual machine using the FreeBSD command line. It creates scripts to initialize, start and stop the BHyve VM and the Docker-ized SageTV Server. While the directions that follow are specific to NAS4Free, there should be enough 'clues' within to run it on other FreeBSD based NASes and FreeBSD itself.

Acknowledgement: Many of the direcitons for seting up and running BHyve are based on steps found here: https://users.monkeybrains.net/support/bhyve

Basic Steps:

1. Initialize BHyve
2. Create an Ubuntu VM under BHyve
3. Start BHyve and the Ubuntu Server Installer
4. Install Ubuntu onto the Virtual Machine
5. Create and test scripts to control the Ubnuntu VM
6. Add scripts to NAS4Free startup and shutdown
7. Optional Ubuntu Tweeks
8. Ubuntu prequisties for SageTV Server
9. Install SageTV Server for Docker
10. Run Docker SageTV server for the first time

At the completion of these steps, you should have a functional SageTV server that runs on NAS4Free and survives a system reboot.


Assumpitons:

• NAS4Free 11 host OS has been setup and is functioning normally.
• The use of ZFS is assumed (although not required), therefore a basic understanding of the ZFS filesystem and terminology will be helpful in interpreting this guide.
• At least one ZFS dataset is defined to store recorded TV. These may be individual disks or a multi-disk RAID array...it doesn't matter. This dataset may or may not be shared over the network, but will be need to be shared via NFS (steps below) to allow access to the virtual machine.
• Optional: One or more additional ZFS datasets to store media (movies, music, etc).
• An additional ZFS dataset to store the BHyve files and the Ubuntu virtual machine. It is not necessary for this dataset to be exclusively reserved for BHyve or to be empty, but this dataset should not be shared over the network for reasons of security. It must also have approximately 40GB of free space for the virtual HDD, Ubuntu install ISO, and ancillary files for BHyve.
• SSH is enabled on NAS4Free and a suitable client (such as PUTTy) is installed on at least one machine on the same network as NAS4Free. This will be used to remotely log in to the NAS4Free and Ubuntu terminals.

Steps:

1. Initialize BHyve
Load the virtualization (vmm) kernal module and configure virtual network (note: I tried some of these steps in the NAS4Free GUI without success, so it seems it must be done by command line). Log into the NAS4Free SSH shell (using PuTTy or similar). The following assume the user is a super user (issuing su or loging in as root), thus avoiding having to sudo every line:

# kldload vmm if_tap if_bridge
# sysctl net.link.tap.up_on_open=1
# sysctl net.inet.ip.forwarding=1
# echo "net.link.tap.up_on_open=1" >> /etc/sysctl.conf
# ifconfig tap1 create
# ifconfig bridge0 create
# ifconfig bridge0 addm tap1 addm igb0 up
				  ^^^^
	(Substitute your network adapter if not igb0)

Note: the Kernel module 'if_bridge' is apparently loaded by default on NAS4Free but may be required on other FreeBSD OS's. In NAS4Free you'll simply get an error explaining that it's already loaded.

Create BHyve directories:
As noted previously, the location of the BHyve files is not critical as a new BHyve directory will be created. For performance reasons, the BHyve directory should be located on an SSD. You may, of course, use an existing directory.

# mkdir /mnt/<pool>/<dataset>/bhyve

Now make an Virtual Machine directory and change to it. The virtual machine name is not critical, but for consistency this name should be used throughout your virtual machine creation. This guide will use the name "UbuntuVM".

# mkdir /mnt/<pool>/<dataset>/bhyve/UbuntuVM
# cd /mnt/<pool>/<dataset>/bhyve/UbuntuVM

Several of the next steps assume you are in the above UbuntuVM directory. Do not change out of this directory until instructed otherwise. If you must reboot NAS4Free or change directories, be sure to cd to the above directory otherwise files will end up out of place.

2. Create an Ubuntu VM under BHyve
You can of course choose to install a different OS if you desire. I chose Ubuntu mostly out of familiarity and the Server variant due to it being relatively light weight. An example of how to install and use CoreOS (a Docker only OS) is here: https://forums.plex.tv/discussion/26...eebsd-nas4free

Retrieve the Ubuntu install CD ISO:
The following assumes Ubuntu Server verison 16.04.2, the most recent LTS release available at this time.

# fetch http://releases.ubuntu.com/16.04.2/ubuntu-16.04.2-server-amd64.iso

Create a virtual HDD for the machine:
The HDD size below (24g) is ultimately up to you. The minimum suggested size for an Ubuntu install on Virtualbox is 10GB. Keep in mind that this must also support a swap file, so actual usable space will be less. For a system that only hosts Docker and the SageTV server, not a great deal of space is needed, but 10GB is probably a bit "tight".

# truncate -s 24g UbuntuVM.img

Create a map file to tell BHyve what devices each file represents, substituting the actual path of your image files..

# nano device.map
(hd0) /mnt/<pool>/<dataset>/bhyve/UbuntuVM/UbuntuVM.img
(cd0) /mnt/<pool>/<dataset>/bhyve/UbuntuVM/ubuntu-16.04.2-server-amd64.iso

3. Start BHyve and the Ubuntu Server Installer
Still as su, type the following commands. Order here is important, enter them in the order given. NOTE: NAS4Free appears to have included grub2-boot "out of the box". If the grub-hyve command is missing on your system, grub2-boot will also need to be installed.

# pkg update
# pkg install grub2-bhyve

Make sure there are no other instances of a VM of the same name which will cause conflict. If no machine is found, an error "UbuntuVM is not created." will be produced. This is normal. This command is important to issue if you find yourself having to start over.

# bhyvectl --vm=UbuntuVM --destroy

The next command mounts the ISO image defined in the device map, and launches grub on the CD. This also specifies RAM for the VM, which is another judgement call. Virtualbox recommends 1G of RAM minimum. I have chosen 3G (-M 3096) to accommodate this recommendation, plus up to a 2GB java heap for SageTV.

# grub-bhyve -r cd0 \
 -m /mnt/<pool>/<dataset>/bhyve/UbuntuVM/device.map \
 -M 3096 UbuntuVM

If you have succeeded, a grub menu will appear on your terminal window. The first option will be to "Install Ubuntu". Select it and press enter.
The grub menu will disappear and the NAS4Free command prompt will re-appear. To boot the CD issue the following set of commands. Again, 3G of RAM is used in this example, but also 2 CPU cores (-c 2). If you have a multi-core CPU you probably do not want to assign all cores to the VM simply to prevent SageTV from "dominating" NAS4Free. 2 cores has always proven sufficient for me, so that is why I chose it here.

# bhyve -c 2 -m 3096M -H -P -A \
 -l com1,stdio \
 -s 0:0,hostbridge \
 -s 1:0,lpc -s 2:0,virtio-net,tap1 \
 -s 3,ahci-cd,/mnt/<pool>/<dataset>/bhyve/UbuntuVM/ubuntu-16.04.2 server-amd64.iso \
 -s 4,virtio-blk,/mnt/<pool>/<dataset>/bhyve/UbuntuVM/UbuntuVM.img UbuntuVM

If all goes well, you will be greeted with the first step of the Ubuntu installer in your NAS4Free terminal, which is to select a language.

4. Install Ubuntu onto the Virtual Machine
Follow the prompts to install Ubuntu-Server onto the VM. Generally you can accept the defaults except when they are wrong (for example, if English is not your preferred language). Other exceptions are listed below, in the order you will encounter them.

• Hostname: You should define a hostname. This is how the Ubuntu will identify itself to your network so you can access it by name rather than by an IP address if you wish. "UbuntuVM" generally defines what the machine is and you can use this if you desire, but "SageTVServer" is more specific and a good choice too if SageTV is the only function Ubuntu provides. It's up to you, but keep in mind spaces, special characters, and overly lengthy names will cause problems! Ubuntu will warn you if you get it wrong.
• Full name for the new user: Defines a user that will be able to log in and administer Ubuntu. Type your name or a made up one, it doesn't matter...but you will need to remember who you wrote here.
• Username for your account: Defaults to the first name typed above, but can be changed to something else.
• Partitioning Method: In the interest of keeping it simple, choose the first option. Other options are fine too if you know what you are doing. If you choose the first option, you will get one EXT4 partition and one swap partition on the virtual HDD.
• Automatic Updates: It is best to apply updates manually as installing updates while the SageTV Server is operating can be disruptive. Therefore choose "No Automatic Updates". Unfortunately that does mean you will need to periodically (once a month or so) log in, stop the SageTV server, apply updates, and restart the server.
• Software: In addition to the Standard System Utilities already checked by default, IT IS IMPERATIVE THAT OPENSSH SERVER BE CHECKED, otherwise Ubuntu will be "locked" in the VM with no easy way to access it. Nothing else is needed from this list.

When installation is complete, you will be told to remove the installation CD ROM. Ubuntu will "eject" the virtual CD for you, and if you listen carefully, you might even hear the virtual disk tray open :-). There is nothing more to do here except to continue, allow the installation to finish, at which time the VM will terminate and return you to the NAS4Free command line.

[texneus]

(Part 2 of 2)

5. Create and test scripts to control the Ubnuntu VM
What follows are the text for three sh scripts that will help administer BHyve and UbuntuVM. The first script will be used to re-create BHyve when NAS4Free boots. This is necessary because NAS4Free operates as an embedded OS, meaning BHyve must be re-initialized at each startup. Once BHyve is initialized, this script will chain to a second script to start the Ubuntu VM.

Note the first line you type into the NAS4Free command line to open nano, while all remaining lines can be pasted into nano to create the file. This is somewhat confusing, I know, but it's because FreeBSD uses '#' as the root user prompt (which is the same symbol for a comment in a sh script).
Please pay particular attention to the lines in highlighted bold! These should be the only edits required to make this script work.

# nano UbuntuVM_Boot.sh
#!/bin/sh
#This script sets up BHyve then boots the VM.  The assumption
#here is NAS4Free has just booted and no VM currently exists.
#If the VM does exist it will be forcefully terminated and restarted.
#Data loss is possible in this scenario.

#Edit these lines to define full path to BHyve VM directory and the VM name.
VMPATH=/mnt/<pool>/<dataset>/bhyve/UbuntuVM
VMNAME=UbuntuVM

#Wait for NAS4Free to boot and/or give the the user a chance to abort.
echo Reseting BHyve VM $VMNAME in 30 seconds.
echo Warning:  Loss of data may occur if VM is active.
echo Press CTRL-C to abort...
sleep 30

#Remove the old pid file.
rm "${VMPATH}/bhyve.pid"

#Configure BHyve and the virtual network
kldload vmm if_tap
#If if_bridge is not loaded by default by your OS, uncomment the next line.
#kldload if_bridge
sysctl net.link.tap.up_on_open=1
sysctl net.inet.ip.forwarding=1
echo "net.link.tap.up_on_open=1" >> /etc/sysctl.conf
ifconfig tap1 create
ifconfig bridge0 create
#Change igb0 to match the name of your network adapter
ifconfig bridge0 addm tap1 addm igb0 up

#Chain to the VM start script to boot the virtual machine.
"${VMPATH}/${VMNAME}_Start.sh"

The next script will be used to boot the virtual machine. As created, this script will only boot the default OS defined by grub. This will not be a problem with any version of Ubuntu (that I am aware of), since the default is to boot Ubuntu unless the default was specifically changed. Please pay particular attention to the lines in highlighted bold! These should be the only edits required to make this script work.

# nano UbuntuVM_Start.sh
#!/bin/sh
#This script will boot the specified VM using BHyve.  It
#will also save the process ID of the VM to stop it later.

#Edit these lines to define full path to BHyve VM directory and the VM name.
VMPATH=/mnt/<pool>/<dataset>/bhyve/UbuntuVM
VMNAME=UbuntuVM

#Check for a PID file.  This would indicate the VM is already running.
if [ -f "${VMPATH}/bhyve.pid" ]
then
        echo "It appears this VM is already operational."
        echo "Delete the bhyve.pid file if this is incorrect."
else
        #Destroy any previous VM incarnations
        bhyvectl --vm=$VMNAME --destroy

        #Load Ubuntu w/Grub (Starts first OS only)
        grub-bhyve -m ${VMPATH}/device.map \
        -r hd0,msdos1 -M 3096 $VMNAME > /dev/null

        #Start Ubuntu VM. Change core and memory options as needed.
        bhyve -c 2 -m 3096M -H -P -A \
        -s 0:0,hostbridge \
        -s 1:0,lpc \
        -s 2:0,virtio-net,tap1 \
        -s 3,ahci-cd,${VMPATH}/ubuntu-16.04.2-server-amd64.iso \
        -s 4,virtio-blk,${VMPATH}/${VMNAME}.img $VMNAME &

        #Give bhyve time to start, then save the PID for later.
        sleep 5
        pgrep -fx "bhyve: $VMNAME" > ${VMPATH}/bhyve.pid
fi

The third and final script will be used to stop the virtual machine. This can be called manually to gracefully shut down the VM and will also be called at NAS4Free shutdown. Please pay particular attention to the lines in highlighted bold! These should be the only edits required to make this script work.

# nano UbuntuVM_Stop.sh
#!/bin/sh
#This script will kill the BHyve VM using the bhyve.pid file.
#Per BHyve docs, this is the same as an ACPI shutdown.

#Edit these lines to define full path to BHyve VM directory and the VM name.
VMPATH=/mnt/<pool>/<dataset>/bhyve/UbuntuVM
VMNAME=UbuntuVM

#Check for a PID file.  This would indicate the VM is already running.
if [ -f "${VMPATH}/bhyve.pid" ]
then
        echo Initiating an ACPI shutdown for the BHyve VM $VMNAME
        pkill -F ${VMPATH}/bhyve.pid
        rm ${VMPATH}/bhyve.pid
else
        echo No bhyve.pid file was found.  Are you sure it\'s running?
        echo Try shutting down the VM from it\'s terminal, or check the
        echo following for a process resembling \'bhyve: $VMNAME\'.
        echo Type \'kill PID\' to manually shutdown the VM.
        echo
        ps -auxww | grep bhyve
fi

6. Test and add scripts to NAS4Free startup and shutdown to seemlessly start/stop BHyve
Now, test the scripts and the Ubuntu installation. Make all three scripts executable for the user (which should be root).

# chmod u+x UbuntuVM_Boot.sh UbuntuVM_Start.sh UbuntuVM_Stop.sh

Go ahead and test the scripts and your Ubuntu install if you like at this time.

# ./UbuntuVM_Start.sh

If BHyve successfully starts the machine, you may see a few somewhat innocuous error messages on stdout (I do) after a short delay (equal to the grub menu timeout). You should still be at the NAS4Free command prompt and BHyve runs in the background.

Use an SSH client to log into UbuntuVM and log in to make sure the VM and your account works, then log back out. Use the stop script to shut down the VM. Optionally, you can also shutdown Ubuntu from the Ubuntu shell and manually delete bhyve.pid in the UbuntuVM directory.

# ./UbuntuVM_Stop.sh

Now we'll add the Boot / Stop scripts to NAS4Free. On each boot the scripts will setup BHyve and launch UbuntuVM. On each shutdown the scripts will gracefully shutdown UbuntuVM rather than cut it off in the middle of what ever it happened to be doing at the time.

In the NAS4Free GUI:

• System | Advanced Setup | Command Scripts.
• Create a new script (+ icon at the bottom of the list)
• The first script will create and boot UbuntuVM.
• For Command, type the path to your VM followed by the name of the boot script. It should look like this, but with your actual pool and dataset names substitued where indicated:

/mnt/<pool>/<dataset>/bhyve/UbuntuVM/UbuntuVM_Boot.sh

• The type will be "PostInit", which starts the script after NAS4Free has completely booted.
• Name and comment are as you please.
• Click Add, then repeat the above to add the Stop script.

Command: /mnt/<pool>/<dataset>/bhyve/UbuntuVM/UbuntuVM_Stop.sh
Type:	Shutdown

• Be sure to apply changes when finished to actually add the Startup/Shutdown scripts.

Finally, reboot NAS4Free. Upon startup, UbuntuVM should boot automatically after a 30 second delay (the script does this to allow NAS4Free to boot and be available as quickly as possible, but also to give you a chance to abort if you have accidentally run this script from the command line). Go ahead and use your SSH client to log into the UbuntuVM.

7. Optional Ubuntu Server Tweeks
Once an SSH shell to the VM has been established, the following steps are completely optional and are presented as "ease of use".

This allows you to issue a su command to assume root. IMO, this is much easier than repeatedly having to "sudo" everything.

$ sudo passwd       (enter your password)

You will then be prompted to "Enter new UNIX password", followed by a prompt to retype it to verify. Now instead of having to type sudo on a chain of commands, you can simply type su one time, provide the root password, and type commands normally to execute them as root. Remember to type exit when finished to revert to your normal every day user privledges.

This fixes the VM's IP address to a static value. Do this only if you have a range of IP addresses set aside in your router that are not assigned. You would do this to ensure the IP address of the VM doesn't change, ensuring the server will always be available at a specific address on your home network and helps avoid DNS lookup issues. To do this, edit /etc/network/interfaces with a text editor, such as nano.

$ sudo nano /etc/network/interfaces

Change the iface line to use a static IP assignment, then add address, netmask, gateway, and dns-nameservers values to meet your network's requirements. Example:

auto enp0s3
#iface enp0s3 inet dhcp
iface enp0s3 inet static
address 192.168.1.218
netmask 255.255.255.0
gateway 192.168.1.1
dns-nameservers 192.168.1.1

To restore DHCP, uncomment the first iface line and remove all the following lines.

The VM will need to be restarted for these changes to take effect. When the VM is rebooted, reopen the SSH shell and log in to UbuntuVM prior to continuing.

8. Ubuntu prerequisites for SageTV-Server
The first thing we will do is ensure Ubuntu is up to date.
Type su to assume a root user.

$ su

If you did not enable su in the previous section, you will need to use sudo for each command below that is preceded with a #.

Update Ubuntu-Server. Ubuntu, being based on Debian, uses the Aptitude package manager. Note in recent versions of Ubuntu apt is intended to replace apt-get. Although apt-get still functions, It is no longer necessary and apt is simpler. After the updates, reboot becuase it is likely an updated Linux kernel was included in the updates.

# apt update
# apt upgrade
# reboot

The next thing to do is to share our previously defined RecordedTV and Media directories into the UbuntuVM. This will be done with NFS (Network File System). SMB could be used as well, but NFS is reputed to be higher performance.

• On the NAS4Free GUI: Services | NFS | Settings, then click Enable.
• On the shares tab, add a new NFS share by using the "+" icon at the end of the list of any existing shares.
• Set the share path by navigating to the pool and dataset previously created for RecordedTV: /mnt/<pool>/<dataset>
• For "Map to Root", you want this to be 'Yes'. This ensures full authority over the NFS share is extended to any user (they will appear to the server as "root"). Provided access to the share is restricted to the UbuntuVM only (as noted on the next step), and the UbuntuVM is only used as a SageTV server (not a general work station or file server), the risk should be minimal.
• Authorized Network should be your home network at the minimum, so for example if all the machines on your home network have IP addresses of 192.168.1.xxx, then set the authorized network to 192.168.1.0/24. Even better, if the VM was assgined a static IP, and assuming you do not need any other machine to access these shares through NFS, then put the static IP here: 192.168.1.218/32.
• All directories should be checked, unless for some reason you do not wish SageTV to access sub directories within a NFS share.
• Read Only should be checked if a share is not intended to be modified or managed by SageTV. RecordedTV directories should allow read and write access, but you might want media directories to be read only to prevent accidental deletion by SageTV.
• Click add, then repeat for all datasets that SageTV will need to access. Be sure to Apply Changes when finished to save the NFS shares.

Now we need to setup an NFS client on Ubuntu server:

• Install the client software

# apt install nfs-common

• Add the mount points so they are available at each reboot. To do this, create empty directories to serve as mount points. Assuming these shares are to be accessed in /mnt:

# mkdir /mnt/RecordedTV
(repeat for each NFS share)

• Then add these shares to /etc/fstab. Be sure to specify the full path to the mount point on NAS4Free

# nano /etc/fstab
...
<NAS4FreeIP>:/mnt/<pool>/<dataset> /mnt/RecordedTV nfs auto,nofail,noatime,nolock,intr,tcp,actimeo=1800 0 0
(repeat for each NFS share)

• More information about the options specified here can be found in the man page that describes NFS mounting in the fstab with the man nfs command.

Finally, install Docker. Follow the directions at Docker to install the CE "Community Edition" version of Docker onto Ubuntu.
https://docs.docker.com/engine/insta...ker-ce/ubuntu/

9. Install SageTV Server for Docker
First, find your user, group, and video IDs in Ubuntu. Docker uses the number rather than the name. Docker will then run the SageTV server as the specified user & group rather than as root. To find the number corresponding to each, log into the UbuntuVM, then...

User (PUID): When logged into Ubuntu as the normal user (not su)

$ id

You should see a line or two of user information and groups you belong to. The very first item should be your UID. More than likely it will be UID=1000 unless you have added additional users. This is the PUID.

Group (PGID):

$ getent group | grep <yourgroup>

You should now see a line that looks like <yourgroup>:x:<GID>:. For example, the group "nogroup" shows as nogroup:x:65534:, so the PGID of "nogroup" is 65534.

Video Group (GUID):
This is a system created group. Repeat the above command substituting "video" as <yourgroup>. Most likely it will be group 44 on an Ubuntu system.

$ getent group | grep video

A note on User and Group IDs: Since NAS4Free will be sharing it's folders with Ubuntu, it is likely that user and group IDs will not mesh. For example, if userID 1000 on Ubuntu corresponds to "UserA", and userID 1000 on NAS4Free corresponds to "UserB", the NAS4Free will list as UserB as the owner while on Ubuntu they will show "UserA" as the owner. Likewise for the groupIDs. There is no clear way to syncronize User & Group IDs between the two systems that I am aware of, appart from creating new userIDs with specific ID numbers. In most cases the mismatch should not be problematic.

Now create two scripts to start and stop SageTV Server for Docker. Since SageTV Server typically runs in the /opt directory, this is where the scripts will be created. These scrpits are based on the discussion here: https://forums.sagetv.com/forums/showthread.php?t=64652. Please pay particular attention to the lines in highlighted bold! These should be the only edits required to make this script work.

Notes:

• To create files in the opt directory you will need to be su.
• A RecordedTV share is mandatory, all others are optional and can be repeated as needed until all extra shares are included, or can removed if a RecordedTV share is all there is. All directories will be mounted inside Docker at the path specified (on the right).
• Change GENTUNER/COMMANDIR/COMSKIP to 'Y' if you want to use these features.
• Set the java heap size to the desired size, in MB. 1024 should be enough for most uses, increase if you experience java heap memory errors. If needed, the RAM of the VM may need to be increased.
• For an example of a completed script see the linked thread in the SageTV forums.

# nano /opt/StartSageTV.sh
docker run -d --name sagetv-server \
-v <NFS RecordedTV share path>:/var/media \
-v <OPTIONAL media share path>:/var/<name> \
-v <OPTIONAL (etc)>:/var/<name> \
-v /opt/sagetv:/opt/sagetv \
--net host \
--env OPT_GENTUNER=N \
--env OPT_COMMANDIR=N \
--env OPT_COMSKIP=N \
--env PUID=<your PUID> \
--env PGID=<your GUID> \
--env VIDEO_GUID=<your VIDEO_GUID> \
--env JAVA_MEM_MB=1024 \
--privileged \
--restart always \
-t -i "stuckless/sagetv-server-java8"

# nano /opt/StopSageTV.sh
docker stop sagetv-server
docker rm -f sagetv-server

Finally, make these scripts executable. Since Docker is nomally run as root, only the root user needs the executable privledge:

# chmod u+x /opt/StartSageTV.sh /opt/StopSageTV.sh

10. Run SageTV Server for Docker
This step is easy, with the scripts we created (be sure to use sudo if you are not logged in as root)

# ./StartSageTV.sh

The first time SageTV Server for Docker is ran, Docker will download the required package, then install and configure it, so there may be a significant delay before the SageTV Server is ready on the first run only.

If it is ever necessary to stop the SageTV server:

# ./StopSageTV.sh

Once the SageTV Server is running, Docker will remember it is running and start it automatically when Ubuntu is booted. Since the scripts created boot Ubuntu when NAS4Free is started, SageTV Server normally requires no user intervention when the entire system is restarted. The exception is if SageTV Server is inoperative when the system is shutdown, Docker will not restart the SageTV server when Ubuntu is booted.

Whew!
Congratulations, you are done. At this time simply run a SageTV client or placeshifter, and configure your SageTV!

[stuckless]

Too bad Docker wasn't supported natively... your write up would have been much shorter. Very good write up, lots of details. Thanks for sharing.

[texneus]

Important update for those who might try this:

After updating NAS4Free, several NAS4Free extensions, and Ubuntu itself, I found the Ubuntu VM was no longer booting at system restart, specifically hanging on the grub loader and hogging one CPU core at 100%. What was especially frustrating is manually starting it worked just fine. After many trials, tribulations, and pure guesswork, I have gotten it working again.

The problem seems to occur because as extensions are updated (and presumably new ones when installed) their new init scripts are added at the bottom of the script list. For reasons not entirely clear to me, the "One Button Installer" being run after starting BHyve is an issue. POSSIBLY (although I'm not certain), because I had the preliminary BHyve extension installed, then removed it, it didn't clean up after itself very well. The updated "One Button Installer" now thinks the BHyve extension is installed (even though there is no GUI tab for it), so there seems to be a conflict. I'll have to see why this is later...

The good news to get this working again, all that is needed is to move the UbuntuVM Boot postinit script so that it is the last Postinit script run. For good measure, I also made sure the "One Button Installer" is also the first script to run. To reorder the scripts, click the gear icon on the far right in the NAS4Free GUI under System | Advanced | Command scripts.

[texneus]

I regret I must announce this effort is abandoned as I have run into a road block that for all intents and purposes appears un-resolvable at this time. The issue specifically is OTA streaming issues from the HDHR. Full story follows with what I've tried if you care to read it. Bottom line is I would like this post to stay as "archival material" in case somebody (including myself) tries to get this working again in the future. It showed great promise, but unfortunately this is pretty critical functionality so I'm off to find another solution.

If somebody does manage to get this working properly (and I gather by the tremendous response here that I am the only one doing this ), please post an update!

Background:

Since migrating to Sage v9 my HDHR never did seem to work right. I wrote it off initially to a bad power supply, and after finally replacing the power supply, decided my old HDHR "classic" is on the way out. Replacing it with the HDHR Quattro resulted in no improvements, unfortunately, so that left me poking around with system setup issues on the FreeBSD/BHyve/Ubuntu/Docker combo. As best as I can figure there is random packet loss or perhaps timing issues of the packet flow. On my Windows SageTV client I see occational (not frequent, but often enough to get your attention), dropped frames, brief freezes, tearing, pixelation, and occasionally, complete but temporary corruption of the video where vast chunks are replaced with grey squares. What is really frustrating is this only happens frequently on two channels, while others seem to be largely immune. There are also no issues with a networked Colossus HDMI capture, just HDHR video streams. I cannot explain why Colossus works and HDHR does not, nor can I say why some channels are impacted more than others, but you can probably now see why I was quick to blame an old HDHR for the issue originally.

Things I have tried to get the HDHR working properly:

First I confirmed the glitches are recorded in the recordings. Indeed, the same exact glitches are apparent when rewinding and viewing the recordings in SageTV (windows cleint), SageTV mini-client (android) and even MPC-HC. They're definitely real and are not added during playback. This is definitely a recording phenomena.

Re-aimed the antenna to ensure optimal reception. It had "drifted" to the east a bit and this did seem to help, but did not eliminate the problem.

I later found the HDHR reception *perfect* using the HDHR app in Kodi, then setting up a separate SageTV server on physical (not virtualized hardware). HDHR, Ubuntu-Server, Docker, and SageTV server are confirmed to work just fine together (so relax devs!), and the glitches are not due to reception.

Back to the BHyve: I setup SageTV server directly in Ubuntu to remove the Docker virtualization layer. No change.

I managed to figure out how to setup BHyve to directly access disk space rather than shuttle it through NFS. Used a different HDD than those already in use for SageTV. No change.

I tried to do PCI passthrough to a second NIC to eliminate network virtualization, but NAS4Free simply pukes and won't have anything to do with that (no idea why, no doubt I'm probably doing something wrong). So this is where I throw in the towel. I may revisit sporadically in the future, but I'm crying uncle for now.

[EnterNoEscape]

Just curious here. Did you attempt to verify that some of the UDP traffic streaming from the HDHomeRun wasn't getting dropped? I know SageTV uses native code to receive the stream from the HDHomeRun and I have seen that code insufficiently buffer packets resulting in data loss.

[Parsley]

Interesting. I went down a similar road, but used FreeNAS 11 instead of NAS4Free. I was able to set up an virtual Ubuntu 16.04 server with the included beehyve VM software, then followed the guide + script in these forums for installing SageTV in Ubuntu and getting it to work with an HDHomeRun network tuner. (That sentence might be glossing over things a bit...)

It's been rock solid for a month. I was able to retire the old-but-still-functional Windows Home Server v1 that had been running the SageTV server up to that point for 7 years.

[texneus]

I think I serendipitously found the problem when setting up another machine. I had some older, slower hardware I was going to dedicate to be a SageTV machine. What I instantly noticed when comparing operation of each machine was that NAS4Free had substantially more disk I/O and head "chatter" than a machine running pure Ubuntu when recording. It only occurred to me at that point that ZFS checksums the entire file system, blocks, files, and directories all the way up to the partition so it can detect data loss. It seemed logical that the extra disk I/O was related to having to re-calculate all these checksums as each new section of the recording was written out to disk. It's all just a theory, mind you, but seems logical from what I know about how ZFS works.

So despite what I said before about "throwing in the towel", I installed NAS4Free on said older, slower, machine. In the process I figured out how to pass-through a disk in Bhyve (not the SATA controller, but the actual disk device) and formatted it as EXT4 (like it was under Ubuntu). That put ZFS completely out of the picture, not even as a middle man. Well, what do you know, it all works perfect. Not a single glitch in a full weeks worth of test recordings.

Last weekend I duplicated the setup on the production server, but was shocked to find I still ended up with the same exact problem! So the ZFS theory was a red herring, but it did lead me to deep dive into the NAS4Free settings on each machine. In so doing I found, then remembered three major NAS4Free revisions and two motherboards ago, that I set NAS4Free to use pretty aggressive CPU power management. I changed this from "Adaptive" to "Hi Adaptive" and (knock on wood) it looks like it's working well now. So it seems the root cause is due to a fully idled Skylake CPU (at 200MHz) is too slow and SageTV starts dropping data from the stream (this somewhat dove tails into the SageTV buffering theory mentioned). Hi Adaptive seems to keep the system clock high enough that everything continues to flow as required.

Testing still in process, but results look very promising so far. I have not returned to using a ZFS filesystem but since CPU throttling seems to be the main contributor and Parsley says it works then I have no reason to believe it wouldn't. Seeing the difference though in ZFS vs. EXT4 has me convinced EXT4 is probably the better option here, so I intend to stick with it at least for now.

[texneus]

Originally Posted by EnterNoEscape

Just curious here. Did you attempt to verify that some of the UDP traffic streaming from the HDHomeRun wasn't getting dropped? I know SageTV uses native code to receive the stream from the HDHomeRun and I have seen that code insufficiently buffer packets resulting in data loss.

P.S. How would I go about doing this? From within the UbuntuVM (not the Docker machine) I installed and ran the HDHR utility that flags packet loss, but I never saw any at that level.

[EnterNoEscape]

Originally Posted by texneus

P.S. How would I go about doing this? From within the UbuntuVM (not the Docker machine) I installed and ran the HDHR utility that flags packet loss, but I never saw any at that level.

Interesting. That's basically what I was going to tell you to do (run the utility). Did you also try running the utility and having it write out the stream to the disk you're using for recordings?

I know you're not using it and there doesn't appear to be a good reason to, but OpenDCT will flag continuity issues with the RTP stream in the log which has been very helpful when people report poor quality recordings. Unfortunately SageTV doesn't log any of these events, so it's a little harder to figure out what's going on without additional tools. I know at least one forum user was able to see the packets dropping for their VM, but that was on ESX. You can also adjust the UDP buffering and see if it makes any difference.

I hope some of this rambling is helpful.

[texneus]

It was one of the first things I did so it's been a while but I believe I ran it while watching the channel so I could try and catch it glitching. I never did catch it doing anything so perhaps SageTV the HDHR utility was just enough load to keep the CPU clock up? Who knows...

Interesting about OpenDCT, I might try that if it starts acting up again.

[texneus]

@Parsley, if you're still out there, would you mind sharing how you shared your recording HDDs through BHYVE to the SageTV server? I tried using UFS instead of ZFS last night but the amount disk activity was still horrendous. It makes me wonder if this is actually something to to with NFS shares, like maybe I/O isn't cached by FreeBSD very effectively (or at all). Giving Ubuntu direct access to a disk works quite well, but then it can't be accessed by NAS4Free for sharing over the network.

[Parsley]

I needed Windows access to the storage pool on the FreeNAS server. I pointed the virtual Ubuntu server running SageTV to those Windows (SMB) shares. It might not be the most efficient way to do things, but it was simple. I haven't had any performance issues that I can detect on a human level. Haven't run any tests or diagnostics either though since it all just seemed to work.

This is my server hardware, if it helps calibrate relative performance: Supermicro A1SRi-2758 (Atom Avoton C2758 SOC) with 16GB RAM.

[texneus]

Appreciate the input. So it sounds like you do it similar to this guide, but use CIFS/SMB instead of NFS. When watching a live stream how much HDD activity do you see? When I'm only recording or only watching, the HDD seems "normal" (the occasional flicker of the HDD light), but recording and watching seems to result in almost constant HDD activity. UFS and ZFS behave the same in this regard, so it may be something to do with NFS...