OpenH264 Library Download Issue Workaround

Issue Description

LiveSwitch Media Servers automatically download the Cisco OpenH264 library from ciscobinary.openh264.org during startup to provide H.264 codec support. Connectivity issues when downloading this library can cause Media Servers to hang during startup, preventing them from reaching a registered and running state.

Warning

Impact:

  • Media Servers fail to reach registered and running state
  • H.264 codec support unavailable (VP8/VP9 still work)
  • RTMP service affected

Urgency: Apply this workaround immediately before starting any Media Servers to prevent startup failures.

Best Solution: Upgrade to LiveSwitch 1.24.4 or newer

The optimal solution is upgrading to LiveSwitch 1.24.4, which includes a permanent fix for the OpenH264 download issue. This ensures reliable operation and maintains full H.264 codec support.

  • Benefits: Complete resolution, ongoing support, no workarounds needed
  • Best for: All deployments that can accommodate planned upgrades

Alternative Solution: Pre-Download OpenH264 Library (Linux Instructions)

For older LiveSwitch Server versions that cannot be upgraded soon but require H.264 support, you can manually download and install the OpenH264 library before starting the Media Server or Recording Muxer.

Benefits:

  • Maintains full H.264 codec support
  • Works with older LiveSwitch versions
  • Media Server recognizes existing library and skips download
  • Satisfies Cisco's requirement for per-deployment download

  1. Download and prepare the OpenH264 library:

    # Create directory for OpenH264 library
mkdir -p /opt/openh264
cd /opt/openh264

# Download the library
wget -O libopenh264-1.7.0-linux64.4.so.bz2 http://ciscobinary.openh264.org/libopenh264-1.7.0-linux64.4.so.bz2

# Decompress and prepare the library
bunzip2 libopenh264-1.7.0-linux64.4.so.bz2
mv libopenh264-1.7.0-linux64.4.so libopenh264-1.7.0.so
chmod 755 libopenh264-1.7.0.so

  2. Create symlink in your LiveSwitch installation directory:

    ln -sf /opt/openh264/libopenh264-1.7.0.so /opt/liveswitch/media-server/libopenh264.so.4
ln -sf /opt/openh264/libopenh264-1.7.0.so /opt/liveswitch/recording-muxer/libopenh264.so.4

  3. Start your LiveSwitch services:

    systemctl start media_server
systemctl start recording-muxer

Note: This approach downloads the library once during setup rather than on each service start, but still complies with Cisco's licensing terms.

DNS Blocking Solutions

Block access to ciscobinary.openh264.org to prevent the failed download attempt. This is easy to implement, but H.264 support will be unavailable and Recording Muxer will not work. This is a temporary workaround. Remove these DNS blocks once the OpenH264 download issue is resolved and you want to restore full H.264 codec support. Choose the solution that matches your deployment:

Windows Installation Linux Installation Docker Installation AWS Cloud
  1. Stop LiveSwitch services
  2. Edit hosts file
  3. Add DNS redirect entry
  4. Restart services
  1. Stop LiveSwitch services
  2. Edit /etc/hosts file
  3. Add DNS redirect entry
  4. Restart services
  1. Stop containers
  2. Add hosts mapping to docker run
  3. Restart containers
  1. Create DNS Firewall rule group
  2. Block openh264.org domain
  3. Associate with VPC

Windows Installation

  1. Stop the LiveSwitch Media Servers using Windows Command Prompt as administrator:

    net stop "media server"

  2. Open the hosts file in a text editor as administrator:

    C:\Windows\System32\drivers\etc\hosts

  3. Add the following line to block the OpenH264 download:

    127.0.0.1 ciscobinary.openh264.org

  4. Save the file and restart the LiveSwitch Media Servers:

    net start "media server"

  5. Confirm the Media Server starts successfully after failing the OpenH264 download.

Linux Installation

  1. Stop the LiveSwitch Media Servers:

    sudo systemctl stop media_server

  2. Edit the hosts file:

    /etc/hosts

  3. Add the following line to block the OpenH264 download:

    127.0.0.1 ciscobinary.openh264.org

  4. Save the file and restart the LiveSwitch Media Servers:

    sudo systemctl start media_server

  5. Confirm the Media Server starts successfully after failing the OpenH264 download.

Docker Installation

  1. Stop the existing LiveSwitch Media Server containers:

    sudo docker stop liveswitch-media-server

  2. When recreating your containers, add the hosts mapping to block the OpenH264 download. Update your docker run commands to include:

    --add-host ciscobinary.openh264.org:127.0.0.1

    Example for Media Server:

    sudo docker run -d --name liveswitch-media-server \
  --add-host ciscobinary.openh264.org:127.0.0.1 \
  [your other parameters] \
  frozenmountain/liveswitch-media-server:latest

  3. Confirm the Media Server containers start successfully after failing the OpenH264 download.

AWS Cloud Deployment

For AWS deployments, use DNS Firewall to block the domain at the VPC level:

DNS Firewall rule group creation
  1. Create Rule Group:
    • AWS Console → VPC → DNS Firewall → Rule groups
    • Click Create rule group
    • Name: block-cisco-openh264
DNS Firewall add rule
  1. Add Blocking Rule:
    • Custom domain list
    • Create new domain list
      • Enter list name: block-cisco-openh264
      • Add domain to block: *.openh264.org
    • Action: BLOCK
    • Response: NODATA
    • Click Add rule
DNS Firewall rule configuration
  1. Apply to VPC:
    • VPC associations → Associate VPC
    • Select your VPC
    • Click Associate
VPC association

  1. Test the configuration: SSH onto an EC2 instance on that VPC and test that the domain is now blocked:

    nslookup ciscobinary.openh264.org
# Should fail - no DNS resolution

  2. Restart your Media Servers to confirm they start after failing the OpenH264 download.

After applying the workaround:

  1. Media Servers should start successfully without hanging on OpenH264 download
  2. H.264 support will be unavailable but VP8/VP9 codecs will continue to work
  3. RTMP service will not function until H.264 support is restored