Skip to content

Commit

Permalink
Create Debian package of udm-iptv
Browse files Browse the repository at this point in the history
With the release of the UniFi Dream Machine SE and the UniFi Dream Router, Ubiquiti has recently started transitioning to use UniFi OS as base OS. In contrast, on the UniFi Dream Machine (Pro), UniFi OS was hosted inside a container managed by Podman and UbiOS.

Users have shown [1] that the existing setup using the Podman container for running igmpproxy is feasible on the new devices running UniFi OS. However, this requires setting up Podman manually on these devices, which involves a lot of manual and non-trivial steps.

This process is greatly simplified by simply providing a Debian package that can be installed by the existing `apt` infrastructure that exists in UniFi OS (since it is a derivative of Debian). Furthermore, it enables compatibility with all Ubiquiti devices that use UniFi OS.

This pull request converts the existing scripts into a Debian package. The Docker container is converted into a systemd service managed by UniFi OS and the installer script is now based on `debconf`. 

Before merging, I am looking for feedback from users to see whether this new setup works correctly for their use-cases and verify whether the installation process still remains easy. Please let me know if you experience any issues with this new setup!

Close fabianishere#29 

[1] https://github.com/mories76/udmprose-iptv
  • Loading branch information
fabianishere authored Jan 11, 2022
2 parents 47f1614 + fdb266e commit 59846d3
Show file tree
Hide file tree
Showing 23 changed files with 867 additions and 541 deletions.
7 changes: 7 additions & 0 deletions .github/dependabot.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
# Set update schedule for GitHub Actions
version: 2
updates:
- package-ecosystem: "github-actions"
directory: "/"
schedule:
interval: "weekly"
29 changes: 29 additions & 0 deletions .github/workflows/build.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,29 @@
name: Build

on: pull_request

jobs:
build:
runs-on: [ubuntu-18.04]
if: ${{ !contains(github.event.head_commit.message, 'skip ci') }}
steps:
- name: Checkout Sources
uses: actions/checkout@v2
with:
path: udm-iptv
- name: Setup Dependencies
run: sudo apt-get install devscripts debhelper
- name: Build Package
run: |
cd udm-iptv
debuild -uc -us --lintian-opts --profile debian
- name: Upload Artifacts
uses: actions/upload-artifact@v2
with:
name: build-artifacts
if-no-files-found: error
path: |
*.deb
*.build*
*.changes
*.dsc
64 changes: 64 additions & 0 deletions .github/workflows/release.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,64 @@
name: Release

on:
push:
tags:
- v*

jobs:
build:
name: Build
runs-on: [ubuntu-18.04]
steps:
- name: Checkout Sources
uses: actions/checkout@v2
with:
path: udm-kernel-tools
submodules: recursive
- name: Setup Dependencies
run: sudo apt-get install devscripts debhelper
- name: Build Package
run: |
cd udm-iptv
debuild -uc -us --lintian-opts --profile debian
- name: Upload Artifacts
uses: actions/upload-artifact@v2
with:
name: build-artifacts
if-no-files-found: error
path: |
*.deb
*.build*
*.changes
*.dsc
release:
name: Publish Release
runs-on: [ubuntu-18.04]
needs: build
steps:
- name: Checkout Sources
uses: actions/checkout@v2
- name: Download Artifacts
uses: actions/download-artifact@v2
with:
name: build-artifacts
path: build-artifacts
- name: Format Release Name
id: format_release
run: |
ref="${{ github.ref}}"
release_name=${ref#"refs/tags/"}
echo "::set-output name=release::$release_name"
changelog=$(dpkg-parsechangelog -c 1 -l debian/changelog)
changelog="${changelog//'%'/'%25'}"
changelog="${changelog//$'\n'/'%0A'}"
changelog="${changelog//$'\r'/'%0D'}"
echo "::set-output name=changelog::$changelog"
- name: Create Release
uses: softprops/action-gh-release@v1
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
with:
name: udm-kernel-tools ${{ steps.format_release.outputs.release }}
body: ${{ steps.format_release.outputs.changelog }}
files: build-artifacts/udm-iptv_*.deb
7 changes: 0 additions & 7 deletions Dockerfile

This file was deleted.

177 changes: 92 additions & 85 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,12 +1,13 @@
# IPTV on the UniFi Dream Machine
# IPTV on UniFi OS

This document describes how to set up IPTV on the UniFi Dream Machine (Pro).
This document describes how to set up IPTV on UniFi routing devices based on
UniFi OS, such as the UniFi Dream Machine (UDM) or the UniFi Dream Router (UDR).
These instructions have been tested with the IPTV network from KPN
(ISP in the Netherlands).
However, the general approach should be applicable for other ISPs as well.

For getting IPTV to work on the UniFi Security Gateway, please refer to the
[following guide](https://github.com/basmeerman/unifi-usg-kpn).
For getting IPTV to work on the legacy UniFi Security Gateway, please refer to
the [following guide](https://github.com/basmeerman/unifi-usg-kpn).

## Contents

Expand All @@ -29,9 +30,9 @@ For getting IPTV to work on the UniFi Security Gateway, please refer to the
VLAN4 - IPTV
VLAN6 - Internet
|
+-------+
| UDM/P | - Ubiquiti UniFi Dream Machine
+-------+
+--------+
| Router | - Ubiquiti UniFi device
+--------+
|
LAN
|
Expand All @@ -54,34 +55,37 @@ For getting IPTV to work on the UniFi Security Gateway, please refer to the

Make sure you check the following prerequisites before trying the other steps:

1. The kernel on your UniFi Dream Machine (Pro) must support multicast routing
in order to support IPTV.
Multicast routing is supported natively by the stock kernel from
[firmware version 1.11](https://community.ui.com/releases/UniFi-OS-Dream-Machines-1-11-0/eef95803-6976-499b-9169-bf6dfbbcc209)
and later.
1. The kernel on your UniFi device must support multicast routing
in order to support IPTV:
- **UniFi Dream Machine (Pro)**: Multicast routing is supported natively in the stock kernel since
[firmware version 1.11](https://community.ui.com/releases/UniFi-OS-Dream-Machines-1-11-0/eef95803-6976-499b-9169-bf6dfbbcc209).
If you for some reason cannot use firmware v1.11+, see [udm-kernel](https://github.com/fabianishere/udm-kernel)
for a kernel that supports multicast routing for older firmware versions of the UDM/P.
2. You must
have [on-boot-script](https://github.com/boostchicken/udm-utilities/tree/master/on-boot-script)
installed on your UDM/P.
3. The switches in-between the IPTV decoder and the UDM/P must have IGMP
- **UniFi Dream Machine Pro SE**: You need
[Early Access firmware 2.3.7+](https://community.ui.com/releases/UniFi-OS-Dream-Machine-SE-2-3-7/2cf1632b-bcf6-4b13-a61d-f74f1e51242c)
for multicast routing support.
- **UniFi Dream Router**: Multicast routing is supported by the default
firmware.
2. The switches in-between the IPTV decoder and the UniFi device should have IGMP
snooping enabled. They do not need to be from Ubiquiti necessarily.
4. The FTTP NTU (or any other type of modem) of your ISP must be connected to
one of the WAN ports on the UDM/P.
3. The FTTP NTU (or any other type of modem) of your ISP must be connected to
one of the WAN ports of your UniFi device.

## Setting up Internet Connection

The first step is to set up your internet connection to your ISP with the UDM/P
acting as modem, instead of some intermediate device. These steps might differ
per ISP, so please check the requirements for your ISP.
The first step is to set up your internet connection to your ISP with the UniFi
device acting as modem, instead of some intermediate device. These steps might
differ per ISP, so please check the requirements for your ISP.

Below, we describe the steps for KPN. Feel free to update this document with the
steps necessary for your provider.

### KPN
If you are a customer of KPN, you can set up the WAN connection as follows:

1. In your UniFi Dashboard, go to **Settings > Internet**.
2. Select the WAN port that is connected to the FTTP NTU.
3. Enable **VLAN ID** and set it to the Internet VLAN of your ISP (VLAN6 for
KPN).
3. Enable **VLAN ID** and set it to 6 for KPN.
4. Set **IPv4 Connection** to _PPPoE_.
5. For KPN, **Username** should be set to `internet`.
6. For KPN, **Password** should be set to `internet`.
Expand All @@ -99,9 +103,9 @@ additional DHCP options. You can add these DHCP options as follows:
devices that should receive it.
5. Go to **Advanced > DHCP Option** and add the following options:

| Name | Code | Type | Value |
|-----------|:----:|------------|----------------|
| IPTV | 60 | Text | IPTV_RG |
| Name | Code | Type | Value |
|-----------|:----:|------------|---------------------|
| IPTV | 60 | Text | IPTV_RG |
| Broadcast | 28 | IP Address | _BROADCAST_ADDRESS_ |

Replace _BROADCAST_ADDRESS_ with the broadcast address of your LAN network.
Expand All @@ -116,67 +120,73 @@ additional DHCP options. You can add these DHCP options as follows:

## Configuring Helper Tool

Next, we will use the [udm-iptv](https://hub.docker.com/r/fabianishere/udm-iptv)
container to get IPTV working on your LAN. This container uses
[igmpproxy](https://github.com/pali/igmpproxy) to route multicast IPTV traffic between WAN and LAN.
Next, we will use the udm-iptv package to get IPTV working on your LAN.
This package uses [igmpproxy](https://github.com/pali/igmpproxy) to route
multicast IPTV traffic between WAN and LAN.

### Installation
Before we set up the `udm-iptv` container, make sure you have the
[on-boot-script](https://github.com/boostchicken/udm-utilities/tree/master/on-boot-script)
installed. SSH into your machine and execute the following command:
SSH into your machine and execute the following command:

```bash
sh -c "$(curl -s https://raw.githubusercontent.com/fabianishere/udm-iptv/master/install.sh)"
# Download udm-iptv package
wget https://github.com/fabianishere/udm-iptv/releases/download/v2.0.0/udm-iptv_2.0.0_all.deb
# Download a recent igmpproxy version
wget http://ftp.debian.org/debian/pool/main/i/igmpproxy/igmpproxy_0.3-1_arm64.deb
# Install necessary packages
apt install dialog ./igmpproxy_0.3-1_arm64.deb ./udm-iptv_2.0.0_all.deb
```
If `apt` is not available, make sure you are in UniFi OS (and not UbiOS). Use
`unifi-os shell` to enter UniFi OS from within UbiOS on the UniFi Dream Machine (Pro).

This script will install the `udm-iptv` package onto your device.
The installation process prompts the user with various questions to correctly
configure the package. Below is a useful list of configuration values for various IPTV providers:

| Provider | WAN VLAN | WAN Ranges | Notes |
|---------------|:--------:|-----------------------------------------------------------------------|--------------------------------------------------|
| KPN (NL) | 4 | 213.75.0.0/16 217.166.0.0/16 | DHCP options set to `-O staticroutes -V IPTV_RG` |
| Tweak (NL) | 4 | 239.0.3.0/16 225.0.71.0/24 224.0.0.0/16 | |
| Telekom (DE) | 0 | 232.0.0.0/16 87.141.0.0/16 | Telekom uses VLAN 7 for both internet and IPTV |
| Swisscom (CH) | 0 | 213.3.72.0/24 224.0.0.0/4 | |
| Init7 (CH) | 0 | 224.0.0.0/8 239.0.0.0/8 | |
| MEO (PT) | 0 | 10.159.0.0/16 10.173.0.0/16 194.65.46.0/23 213.13.16.0/20 224.0.0.0/4 |

This script will install a boot script that runs after every boot of your
UniFi Dream Machine and will set up the applications necessary to route
IPTV traffic.
You may also download and inspect the script manually before running it.


Below is a useful list of configuration values for various IPTV providers:
Feel free to update this list with the configuration of your provider.

| Provider | WAN VLAN | WAN Ranges | Notes |
| -------------|:----------:|------------------------------|-------|
| KPN (NL) | 4 | 213.75.0.0/16 217.166.0.0/16 | |
| Telekom (DE) | 0 | 232.0.0.0/16 87.141.0.0/16 | Telekom uses VLAN 7 for both internet and IPTV |
| Swisscom (CH)| 0 | 213.3.72.0/24 224.0.0.0/4 | |
| Init7 (CH)| 0 | 224.0.0.0/8 239.0.0.0/8 | |
The package installs a service that is started during the
boot process of your UniFi device and that will set up the applications
necessary to route IPTV traffic. After installation, the service is automatically
started.

Feel free to update this list with the configuration of your provider.
### Configuration
You can modify the configuration of the service interactively using `dpkg-reconfigure udm-iptv`.
Alternatively, you can modify the configuration at `/etc/udm-iptv.conf` (within UniFi OS).
See below for a reference of the available options to configure.

### Running
After installation, run the IPTV container as follows:
| Environmental Variable | Description | Default |
|-------------------------|---------------------------------------------------------------------------------------------------------|------------------------------------|
| IPTV_WAN_INTERFACE | Interface on which IPTV traffic enters the router | eth8 (on UDM Pro) or eth4 (on UDM) |
| IPTV_WAN_RANGES | IP ranges from which the IPTV traffic originates (separated by spaces) | 213.75.0.0/16 217.166.0.0/16 |
| IPTV_WAN_VLAN | ID of VLAN which carries IPTV traffic (use 0 if no VLAN is used) | 4 |
| IPTV_WAN_VLAN_INTERFACE | Name of the VLAN interface to be created | iptv |
| IPTV_WAN_DHCP_OPTIONS | [DHCP options](https://busybox.net/downloads/BusyBox.html#udhcpc) to send when requesting an IP address | -O staticroutes -V IPTV_RG |
| IPTV_LAN_INTERFACES | Interfaces on which IPTV should be made available | br0 |
| IPTV_IGMPPROXY_DEBUG | Enable debugging for igmpproxy | false |

### Removal
To fully remove an `udm-iptv` installation from your UniFi device, run the follow command:
```bash
/mnt/data/on_boot.d/15-iptv.sh
apt remove dialog igmpproxy udm-iptv
```

### Updating
You can update the IPTV container as follows:

In order to remove all configuration files as well, run the following command:
```bash
podman pull fabianishere/udm-iptv
apt purge dialog igmpproxy udm-iptv
```

### Configuration
You can modify the configuration of the container after installation in the installed
boot script at `/mnt/data/on_boot.d/15-iptv.sh`.
See below for a reference of the available options to configure.

| Environmental Variable | Description | Default |
| ------------------------|----------- |---------|
| IPTV_WAN_INTERFACE | Interface on which IPTV traffic enters the router | eth8 (on UDM Pro) or eth4 (on UDM) |
| IPTV_WAN_RANGES | IP ranges from which the IPTV traffic originates (separated by spaces) | 213.75.0.0/16 217.166.0.0/16 |
| IPTV_WAN_VLAN | ID of VLAN which carries IPTV traffic (use 0 if no VLAN is used) | 4 |
| IPTV_WAN_VLAN_INTERFACE | Name of the VLAN interface to be created | iptv |
| IPTV_WAN_DHCP_OPTIONS | [DHCP options](https://busybox.net/downloads/BusyBox.html#udhcpc) to send when requesting an IP address | -O staticroutes -V IPTV_RG |
| IPTV_LAN_INTERFACES | Interfaces on which IPTV should be made available | br0 |

## Troubleshooting and Known Issues

Below is a non-exhaustive list of issues that might occur while getting IPTV to
run on the UDM/P, as well as troubleshooting steps. Please check these
run on your UniFi device, as well as troubleshooting steps. Please check these
instructions before reporting an issue on issue tracker.

### Debugging DHCP
Expand All @@ -200,36 +210,33 @@ IP address from the IPTV network via DHCP:

### Debugging IGMP Proxy

Use the following steps to debug `igmpproxy` if it is behaving strangely:
Use the following steps to debug `igmpproxy` if it is behaving strangely.
Make sure you are running inside UniFi OS.

1. **Enabling debug logs**
You can enable `igmpproxy` to report debug messages by adding the following
flags to the script in `/mnt/data/on_boot.d/15-iptv.sh`:
```diff
IPTV_WAN_VLAN="4"
IPTV_WAN_DHCP_OPTIONS="-O staticroutes -V IPTV_RG"
IPTV_LAN_INTERFACES="br0"
- IPTV_IGMPPROXY_ARGS=""
+ IPTV_IGMPROXY_ARGS="-d -v"
```
Make sure you run the script afterwards to apply the changes.
You can enable `igmpproxy` to report debug messages by setting `IPTV_IGMPPROXY_DEBUG`
to `true` in the configuration at `/etc/udm-iptv.conf` (within UniFi OS).
Then, restart the service as follows:
```bash
systemctl restart udm-iptv
```
2. **Viewing debug logs**
You may now view the debug logs of `igmpproxy` as follows:
```bash
podman logs iptv
journalctl -u udm-iptv
```

### Reporting an Issue
Please share the diagnostics reported by the boot script when reporting an issue:
Please share the diagnostics reported by the service when reporting an issue:
```bash
/mnt/data/on_boot.d/15-iptv.sh diagnose
udm-iptv-diag
```

## Contributing
Questions, suggestions and contributions are welcome and appreciated!
You can contribute in various meaningful ways:

* Report a bug through [Github issues](https://github.com/fabianishere/udm-iptv/issues).
* Report a bug through [GitHub issues](https://github.com/fabianishere/udm-iptv/issues).
* Contribute improvements to the documentation (e.g., configuration for other ISPs).
* Help answer questions on our [Discussions](https://github.com/fabianishere/udm-iptv/discussions) page.

Expand Down
6 changes: 6 additions & 0 deletions debian/changelog
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
udm-iptv (2.0.0) stable; urgency=medium

* Initial release of udm-iptv as Debian package.
* Add support for UDM Pro SE and UDR.

-- Fabian Mastenbroek <[email protected]> Sat, 8 Jan 2022 12:00:00 +0100
1 change: 1 addition & 0 deletions debian/compat
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
11
Loading

0 comments on commit 59846d3

Please sign in to comment.