explore
Resources
more
legal
support
Industries
Truetime Solutions™
Truetime Solutions™
Products
Resources
Technology
Partners
Red5 Pro
Red5 Cloud
Red5 Pro
Red5 Cloud

Red5 Documentation

 

Upgrading from Red5 Pro v14 to v15
Discuss on Slack

Upgrading from Red5 Pro v14 to v15

Upgrading Red5 Pro Server from v14 to v15

This guide covers upgrading a stand-alone Red5 Pro Server installation from version 14.x to version 15.0.0. This is a minor version upgrade with no infrastructure changes, making it a straightforward process.

What’s Different in v15

v15 is a feature and stability release built on the same infrastructure as v14:

New Features in v15

  • Conference API included in Stream Manager 2.0
  • SRT egress support for advanced streaming workflows
  • Hyper-V support for virtualization environments
  • JWT support in SimpleAuth plugin for token-based authentication
  • Mixer image overlays for enhanced video composition

Improvements in v15

  • Stream Manager places nodes INSERVICE on ClusterNodeEvents
  • Mixer A/V synchronization reliability improvements
  • Configurable group.instance.id via environment variable
  • Kafka topic retention periods adjusted for long-term stability
  • AutoscalePlugin can reliably recreate Kafka producer
  • Open Source core upgraded to 2.0.22
  • Upgraded Node version in HTML5 SDK
  • Predictable node type targeting in Stream Manager provisions

Bug Fixes in v15

  • Datachannel establishment now allows NetStream.Publish.IsAvailable
  • Social media push for Facebook now working properly (critical fix)
  • WHIP connections no longer momentarily report as WHEP
  • S3 uploads for recordings now retry on failures (important for reliability)

No Breaking Changes

✅ Java 21 – Same as v14
✅ Tomcat 11 – Same as v14
✅ SSL Configuration – Same as v14
✅ Configuration Files – Fully compatible

Prerequisites

Before beginning the upgrade, ensure you have:

  1. Access to your Red5 Pro account at https://account.red5.net/login
  2. Red5 Pro v15.0.0 server distribution downloaded
  3. Valid Red5 Pro license key (included in server download)
  4. Root or sudo access to your server
  5. Current v14.x installation location (typically /usr/local/red5pro)
  6. Backup of custom configurations (see Backup section below)
  7. Maintenance window – Plan for 15-30 minutes of downtime

Quick Compatibility Check

# Verify you're running v14
curl -s http://localhost:5080 | grep -i "14." || cat /usr/local/red5pro/log/red5.log | grep "version" | head -1

# Verify Java 21 is installed
java -version
# Should show: openjdk version "21.x.x"

# Check disk space (need ~2GB)
df -h /usr/local/

Step 1: Backup Your Current Installation

IMPORTANT: Always create a backup before upgrading, even for minor updates.

1.1 Stop the Red5 Pro Service

# Stop the service
sudo systemctl stop red5pro

# Wait for graceful shutdown (30 seconds)
sleep 30

# Verify Red5 Pro is stopped
netstat -an | grep ':5080'
# Should return nothing

1.2 Create Backup

# Create backup directory if it doesn't exist
sudo mkdir -p /opt/red5pro-backups

# Create compressed backup with timestamp
cd /usr/local
sudo tar -czf /opt/red5pro-backups/red5pro-v14-backup-$(date +%Y%m%d-%H%M%S).tar.gz red5pro/

# Verify backup
ls -lh /opt/red5pro-backups/

1.3 Document Current Configuration (Optional)

For reference, snapshot your key settings:

cat > /tmp/red5pro-v14-config.txt <<EOF
Red5 Pro v14 Configuration - $(date)
====================================

Current Version: $(grep -i "version" /usr/local/red5pro/log/red5.log | head -1)
Java Version: $(java -version 2>&1 | head -1)
Red5 Directory: /usr/local/red5pro

Custom Webapps:
$(ls -1 /usr/local/red5pro/webapps/ | grep -v "^live$|^root$|^webrtcexamples$|^streammanager$|^inspector$|^api$")

Service Status:
$(systemctl status red5pro | head -5)
EOF

cat /tmp/red5pro-v14-config.txt

Step 2: Prepare the v15 Installation

2.1 Upload and Extract v15 Distribution

# Upload red5pro-server-15.0.0.zip to /tmp/ via SFTP/SCP

# Verify upload
ls -lh /tmp/red5pro-server-15.0.0.zip

# Extract to /usr/local/ (NOT into the existing red5pro directory)
cd /usr/local
sudo unzip /tmp/red5pro-server-15.0.0.zip

# Verify extraction
ls -la /usr/local/red5pro-server-15.0.0/

2.2 Verify License Key

# Check LICENSE.KEY exists
ls -la /usr/local/red5pro-server-15.0.0/LICENSE.KEY

# If you have an updated license, verify it matches your account
# https://account.red5.net/overview

Step 3: Migrate Configuration Files

Since v14 and v15 share the same infrastructure, configuration migration is straightforward.

RULE: Manually update configuration files. Do NOT copy directly (some defaults may have improved).

3.1 Migrate Core Configuration

red5.properties

# Compare the two files
diff /usr/local/red5pro/conf/red5.properties 
     /usr/local/red5pro-server-15.0.0/conf/red5.properties

Migrate these common customizations:

# Ports (if customized)
http.port=5080
https.port=443
rtmp.port=1935
rtmps.port=8443

# SSL Configuration (same as v14)
secure.enabled=true
websocket.enabled=true
rtmps.keystorepass=yourpassword
rtmps.keystorefile=/path/to/keystore.jks
rtmps.truststorepass=yourpassword
rtmps.truststorefile=/path/to/truststore.jks

# Performance settings (if customized)
http.max_threads=20
http.acceptor_thread_count=10
http.processor_cache=20

Copy your customizations to the new file:

sudo nano /usr/local/red5pro-server-15.0.0/conf/red5.properties
# Manually apply your settings

3.2 Migrate Plugin Configurations

WebRTC Plugin

# If you customized WebRTC settings
sudo diff /usr/local/red5pro/conf/webrtc-plugin.properties 
           /usr/local/red5pro-server-15.0.0/conf/webrtc-plugin.properties

# If differences exist, manually apply your customizations
sudo nano /usr/local/red5pro-server-15.0.0/conf/webrtc-plugin.properties

Network Configuration

# If using forced IPs or custom ICE settings
sudo diff /usr/local/red5pro/conf/network.properties 
           /usr/local/red5pro-server-15.0.0/conf/network.properties

# Manually apply customizations
sudo nano /usr/local/red5pro-server-15.0.0/conf/network.properties

Common network settings:

force.public.ip=your-public-ip
force.local.ip=your-private-ip
check.port.availability=true

SimpleAuth Plugin (NEW: JWT Support in v15!)

# Copy existing auth configuration
sudo cp /usr/local/red5pro/conf/simple-auth-plugin.properties 
        /usr/local/red5pro-server-15.0.0/conf/simple-auth-plugin.properties

sudo cp /usr/local/red5pro/conf/simple-auth-plugin.credentials 
        /usr/local/red5pro-server-15.0.0/conf/simple-auth-plugin.credentials

NEW in v15: JWT token support is now available. To enable JWT authentication, add to simple-auth-plugin.properties:

# Enable JWT support (new in v15)
jwt.enabled=true
jwt.secret=your-secret-key-here
jwt.algorithm=HS256
jwt.expiration=3600

See JWT Authentication Guide for details.

Cloud Storage Plugin

# If using cloud storage
sudo cp /usr/local/red5pro/conf/cloudstorage-plugin.properties 
        /usr/local/red5pro-server-15.0.0/conf/cloudstorage-plugin.properties

Good news: v15 includes automatic retry for S3 upload failures, making your recordings more reliable.

3.3 Migrate Cluster Configuration (if applicable)

# If using static clustering
sudo cp /usr/local/red5pro/conf/cluster.xml 
        /usr/local/red5pro-server-15.0.0/conf/cluster.xml

3.4 Migrate HLS Configuration (if customized)

# If you customized HLS settings
sudo diff /usr/local/red5pro/conf/hlsconfig.xml 
           /usr/local/red5pro-server-15.0.0/conf/hlsconfig.xml

# Apply customizations if needed
sudo nano /usr/local/red5pro-server-15.0.0/conf/hlsconfig.xml

3.5 Migrate Restreamer/SRT Configuration (if applicable)

# If using SRT restreamer
sudo cp /usr/local/red5pro/conf/restreamer-plugin.properties 
        /usr/local/red5pro-server-15.0.0/conf/restreamer-plugin.properties

NEW in v15: SRT egress support is now available for advanced streaming workflows.

3.6 Migrate API Configuration (if applicable)

# If using the Server API
sudo cp /usr/local/red5pro/webapps/api/WEB-INF/red5-web.properties 
        /usr/local/red5pro-server-15.0.0/webapps/api/WEB-INF/red5-web.properties

sudo cp /usr/local/red5pro/webapps/api/WEB-INF/security/hosts.txt 
        /usr/local/red5pro-server-15.0.0/webapps/api/WEB-INF/security/hosts.txt

3.7 Copy Custom Webapps

# List your custom webapps (excluding built-in ones)
ls -1 /usr/local/red5pro/webapps/ | grep -v "^live$|^root$|^webrtcexamples$|^streammanager$|^inspector$|^api$"

# Copy each custom webapp
# Example:
sudo cp -r /usr/local/red5pro/webapps/myapp 
           /usr/local/red5pro-server-15.0.0/webapps/myapp

Step 4: Update Service Configuration

The service file is compatible between v14 and v15, but it’s good practice to use the new one.

4.1 Update red5pro.service

# Copy new service file
sudo cp /usr/local/red5pro-server-15.0.0/red5pro.service /lib/systemd/system/red5pro.service

# Ensure correct permissions
sudo chmod 644 /lib/systemd/system/red5pro.service

# Edit to verify/update paths
sudo nano /lib/systemd/system/red5pro.service

Verify these settings:

[Unit]
Description=Red5 Pro
Wants=network-online.target
After=network.target network-online.target

[Service]
Type=forking
User=root
LimitNOFILE=1000000

# Verify JAVA_HOME is correct for Java 21
# Ubuntu:
Environment=JAVA_HOME=/usr/lib/jvm/java-21-openjdk-amd64
# CentOS:
# Environment=JAVA_HOME=/usr/lib/jvm/jre-21

# Point to NEW v15 directory (temporarily)
Environment=RED5_HOME=/usr/local/red5pro-server-15.0.0

ExecStartPre=-/usr/bin/killall -q CefRenderer
WorkingDirectory=/usr/local/red5pro-server-15.0.0
ExecStart=/usr/local/red5pro-server-15.0.0/red5pro.sh start
ExecStop=/usr/local/red5pro-server-15.0.0/red5pro.sh stop
ExecReload=/usr/local/red5pro-server-15.0.0/red5pro.sh restart

[Install]
WantedBy=multi-user.target

4.2 Reload Systemd

sudo systemctl daemon-reload

Step 5: Test the v15 Installation

Always test before finalizing the upgrade.

5.1 Start Red5 Pro v15

# Start the service
sudo systemctl start red5pro

# Monitor startup
sudo tail -f /usr/local/red5pro-server-15.0.0/log/red5.log

Watch for:

  • Server started message
  • No ERROR messages
  • Plugins loaded successfully

5.2 Verify Service Status

# Check systemd status
sudo systemctl status red5pro

# Verify port 5080 is listening
netstat -an | grep ':5080'

# Check Java process
ps aux | grep java | grep red5

5.3 Test via Web Browser

  1. Navigate to http://your-server-ip:5080
  2. Verify version shows 15.0.0 in the top-left corner
  3. Welcome page should load without errors

5.4 Test Core Functionality

Test RTMP Publishing

# Using OBS or ffmpeg
ffmpeg -re -i test.mp4 -c:v copy -c:a copy -f flv rtmp://your-server:1935/live/teststream

Test WebRTC (if using SSL)

  1. Navigate to https://your-domain:443/webrtcexamples/
  2. Test publisher page
  3. Test subscriber page
  4. Verify audio/video works

Test API (if configured)

# Test API endpoint
curl http://your-server:5080/api/v1/admin/event/app/live

5.5 Review Logs

# Check for any errors
grep -i "error" /usr/local/red5pro-server-15.0.0/log/red5.log | tail -20

# Verify plugins loaded
grep -i "plugin" /usr/local/red5pro-server-15.0.0/log/red5.log | grep -i "loaded"

# Check for warnings
grep -i "warn" /usr/local/red5pro-server-15.0.0/log/red5.log | tail -20

5.6 Test New v15 Features (Optional)

Test Social Pusher (Fixed in v15)

If you use Facebook streaming:

# Test Facebook push
# This feature had issues in v14 and is now fixed in v15
grep -i "facebook|social" /usr/local/red5pro-server-15.0.0/log/red5.log

Test S3 Recording Reliability (Improved in v15)

If you record to S3:

# Record a test stream and verify upload
# v15 now retries failed uploads automatically
grep -i "s3|cloudstorage" /usr/local/red5pro-server-15.0.0/log/red5.log

Step 6: Finalize the Upgrade

Once testing confirms everything works correctly.

6.1 Stop the Service

sudo systemctl stop red5pro

6.2 Switch Directories

# Rename old v14 directory
sudo mv /usr/local/red5pro /usr/local/red5pro-v14-old

# Rename new v15 directory to standard name
sudo mv /usr/local/red5pro-server-15.0.0 /usr/local/red5pro

6.3 Update Service File Paths

# Edit service file
sudo nano /lib/systemd/system/red5pro.service

Change all paths from /usr/local/red5pro-server-15.0.0 to /usr/local/red5pro:

Environment=RED5_HOME=/usr/local/red5pro
WorkingDirectory=/usr/local/red5pro
ExecStart=/usr/local/red5pro/red5pro.sh start
ExecStop=/usr/local/red5pro/red5pro.sh stop
ExecReload=/usr/local/red5pro/red5pro.sh restart

6.4 Reload and Start

# Reload systemd
sudo systemctl daemon-reload

# Enable service on boot (should already be enabled)
sudo systemctl enable red5pro

# Start the service
sudo systemctl start red5pro

# Verify status
sudo systemctl status red5pro

6.5 Final Verification

# Check version via HTTP
curl -s http://localhost:5080 | grep "15.0" || echo "Check browser"

# Verify in browser
# Navigate to http://your-server-ip:5080
# Version should show 15.0.0

# Test reboot persistence (optional)
sudo reboot
# After reboot:
sudo systemctl status red5pro

Step 7: Explore New v15 Features

Now that you’ve upgraded, take advantage of new features:

7.1 JWT Authentication (SimpleAuth Plugin)

If you want token-based authentication instead of username/password:

  1. Edit /usr/local/red5pro/conf/simple-auth-plugin.properties
  2. Add JWT configuration: 
    jwt.enabled=true
jwt.secret=your-secure-secret-key
jwt.algorithm=HS256
jwt.expiration=3600
  3. Restart Red5 Pro
  4. Generate JWT tokens using your secret key
  5. Use tokens in publish/subscribe URLs

7.2 Conference API (Stream Manager 2.0)

If you’re using Stream Manager 2.0, v15 includes a new Conference API:

  • Multi-party video conferencing support
  • Dynamic participant management
  • Conference room creation and management
  • See Conference API Documentation for details

7.3 SRT Egress Support

v15 adds SRT egress capabilities:

  • Stream out to SRT destinations
  • Complements existing SRT ingress
  • Configure in restreamer-plugin.properties
  • See SRT Documentation for details

7.4 Mixer Image Overlays

If you use the Red5 Pro Mixer:

  • Add image overlays to mixed streams
  • Watermarks, logos, branding
  • Dynamic image composition
  • See Mixer Documentation for details

7.5 Hyper-V Support

v15 is now certified for Hyper-V virtualization environments:

  • Run Red5 Pro in Hyper-V VMs
  • Full performance and feature support
  • Same configuration as other platforms

Post-Upgrade Tasks

8.1 Monitor Performance

Watch your server for the first 24-48 hours:

# Monitor resource usage
htop

# Watch logs for issues
sudo tail -f /usr/local/red5pro/log/red5.log

# Check systemd journal
sudo journalctl -u red5pro -f

8.2 Update Client Applications

Notify your development team about v15 features:

  • JWT authentication available in SimpleAuth
  • Conference API if using Stream Manager 2.0
  • Improved reliability for Facebook social pusher
  • Automatic S3 retry for recordings

8.3 Test Facebook Social Pusher (if applicable)

If you had issues with Facebook streaming in v14:

# Test Facebook push functionality
# This was fixed in v15
grep -i "facebook" /usr/local/red5pro/log/red5.log

8.4 Verify S3 Recording Reliability

If you use S3 for recordings:

# Record several test streams
# v15 now automatically retries failed uploads
grep -i "s3.*retry|s3.*failed|cloudstorage" /usr/local/red5pro/log/red5.log

8.5 Clean Up Old Installation (After 7+ Days)

Once you’ve confirmed v15 is stable:

# Remove old v14 directory
sudo rm -rf /usr/local/red5pro-v14-old

# Keep backup for historical purposes
ls -lh /opt/red5pro-backups/

Rollback Procedure

If you encounter critical issues with v15, you can rollback to v14.

Quick Rollback Steps

# 1. Stop v15
sudo systemctl stop red5pro

# 2. Restore v14 from backup
cd /usr/local
sudo rm -rf red5pro
sudo tar -xzf /opt/red5pro-backups/red5pro-v14-backup-*.tar.gz

# 3. Update service file (if needed)
sudo nano /lib/systemd/system/red5pro.service
# Ensure paths point to /usr/local/red5pro

# 4. Reload and start
sudo systemctl daemon-reload
sudo systemctl start red5pro

# 5. Verify
sudo systemctl status red5pro
curl http://localhost:5080

Troubleshooting

Issue: Service Fails to Start

# Check detailed errors
sudo journalctl -u red5pro -n 50 --no-pager

# Common causes:
# - Configuration syntax error
# - Port already in use
# - Missing dependency

# Verify ports are free
sudo netstat -tulpn | grep ':5080|:1935|:443'

# Check configuration syntax
grep -i "error" /usr/local/red5pro/log/red5.log

Issue: WebRTC Not Working

# Verify SSL configuration
grep -i "secure.enabled|websocket.enabled" /usr/local/red5pro/conf/red5.properties
# Should show both as true

# Check keystore/truststore
ls -la $(grep "keystorefile" /usr/local/red5pro/conf/red5.properties | cut -d= -f2)

# Verify WebRTC plugin loaded
grep -i "webrtc.*loaded" /usr/local/red5pro/log/red5.log

Issue: Cluster Not Connecting

# Check cluster.xml configuration
sudo nano /usr/local/red5pro/conf/cluster.xml

# Verify network connectivity between nodes
ping origin-ip

# Check logs for cluster errors
grep -i "cluster" /usr/local/red5pro/log/red5.log | tail -20

Issue: Social Pusher Still Failing

# Check social pusher configuration
grep -i "social" /usr/local/red5pro/log/red5.log

# Verify credentials are correct
sudo nano /usr/local/red5pro/webapps/live/WEB-INF/red5-web.xml

# Test Facebook API connectivity
curl -I https://graph.facebook.com/

Issue: S3 Uploads Failing

# Check cloud storage configuration
cat /usr/local/red5pro/conf/cloudstorage-plugin.properties

# Verify credentials and bucket access
# Test AWS credentials manually
aws s3 ls s3://your-bucket-name/

# Check logs for retry attempts (new in v15)
grep -i "s3.*retry|cloudstorage.*retry" /usr/local/red5pro/log/red5.log

Performance Comparison: v14 vs v15

You may notice these improvements in v15:

Stability Improvements

  • Mixer A/V sync: More reliable audio/video synchronization
  • Kafka stability: Better long-term stability for Stream Manager deployments
  • AutoscalePlugin: More reliable Kafka producer recreation

Bug Fixes

  • Facebook Social Pusher: Now works reliably (was broken in some v14 scenarios)
  • S3 Recordings: Automatic retry on failures (was manual in v14)
  • WHIP/WHEP reporting: Correct connection type reporting
  • Data Channel: Properly triggers NetStream.Publish.IsAvailable

Additional Resources

Support

If you encounter issues during the upgrade:

  1. Check Red5 Pro Known Issues
  2. Review Troubleshooting Guide
  3. Contact support: support@red5.net
  4. Include logs: /usr/local/red5pro/log/red5.log

Summary

Upgrading from v14 to v15 is straightforward because:

✅ Same Java 21 runtime
✅ Same Tomcat 11 container
✅ Same configuration structure
✅ No breaking changes
✅ Focus on features and stability

The upgrade should take 15-30 minutes with minimal risk. Enjoy the new features!