Upgrading Red5 Pro Server from v13 to v15

This guide covers upgrading a stand-alone Red5 Pro Server installation from version 13.x to version 15.0.0. This is a major version upgrade that includes significant infrastructure changes.

Important: Major Changes in v14/v15

Upgrading from v13 to v15 involves several critical infrastructure changes introduced in v14 and maintained in v15:

Java Runtime Upgrade (v14+)

• v13 uses Java 11 → v15 requires Java 21
• This is a mandatory upgrade that affects all installations
• Custom plugins must be recompiled for JDK 21 compatibility

Tomcat Upgrade (v14+)

• v13 uses Tomcat 8.5 → v15 uses Tomcat 11
• Custom webapps may need updates for Tomcat 11 compatibility
• Tomcat Migration Guide

SSL Configuration Simplification (v14+)

• v13: Requires editing both red5.properties and jee-container.xml
• v15: Only requires editing red5.properties (simplified)
• New properties: secure.enabled=true and websocket.enabled=true

Removed Features

• RTMPE removed in v14 – Use RTMPS instead
• Shared Objects removed in v13 – No longer available

---

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 v13.x installation location (typically /usr/local/red5pro)
6. Backup of all custom configurations (see Backup section below)
7. Maintenance window – Plan for 30-60 minutes of downtime

System Requirements Check

Verify your system meets the requirements for v15:

# Check current Java version
java -version

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

# Check current Red5 Pro version
cat /usr/local/red5pro/red5-server.jar | grep -i "Implementation-Version" || echo "Version in welcome page"

---

Step 1: Backup Your Current Installation

CRITICAL: Always create a complete backup before upgrading.

1.1 Stop the Red5 Pro Service

# If running as systemd service
sudo systemctl stop red5pro

# If running as init.d service
sudo /etc/init.d/red5pro stop

# If running manually
cd /usr/local/red5pro && sudo ./red5-shutdown.sh

Wait 30-60 seconds for the server to fully shut down.

Verify Red5 Pro is stopped:

# Should show nothing
netstat -an | grep ':5080'

1.2 Create Backup

# Create backup directory
sudo mkdir -p /opt/red5pro-backups
cd /usr/local

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

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

1.3 Document Your Custom Configurations

Create a reference document of your current settings:

# Create a configuration snapshot
cat > /tmp/red5pro-v13-config-notes.txt <<EOF
Red5 Pro v13 Configuration Snapshot - $(date)
================================================

JAVA_HOME: $JAVA_HOME
Red5 Pro Directory: /usr/local/red5pro

Configuration Files to Review:
- conf/red5.properties (ports, SSL settings)
- conf/jee-container.xml (Tomcat SSL configuration)
- conf/cluster.xml (if using clustering)
- conf/webrtc-plugin.properties (WebRTC settings)
- conf/simple-auth-plugin.* (authentication)
- conf/network.properties (forced IPs, ICE settings)
- conf/hlsconfig.xml (HLS configuration)
- conf/cloudstorage-plugin.properties (cloud storage)
- webapps/api/WEB-INF/red5-web.properties (API settings)
- webapps/api/WEB-INF/security/hosts.txt (API security)
- webapps/live/WEB-INF/red5-web.xml (live app settings)
- LICENSE.KEY (license file)

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

Service Configuration:
$(systemctl status red5pro 2>/dev/null || echo "Not running as systemd service")
EOF

cat /tmp/red5pro-v13-config-notes.txt

---

Step 2: Install Java 21

v15 requires Java 21. v13 used Java 11, so you must upgrade.

2.1 Install Java 21 (Ubuntu/Debian)

# Update package lists
sudo apt-get update

# Install OpenJDK 21
sudo apt-get install -y openjdk-21-jdk

# Verify installation
java -version
# Should show: openjdk version "21.x.x"

2.2 Install Java 21 (CentOS/RHEL)

# Update package lists
sudo yum -y update

# Install OpenJDK 21
sudo yum -y install java-21-openjdk java-21-openjdk-devel

# Verify installation
java -version
# Should show: openjdk version "21.x.x"

2.3 Update JAVA_HOME

# Find Java 21 installation path
sudo update-alternatives --config java
# Note the path, typically: /usr/lib/jvm/java-21-openjdk-amd64

# For Ubuntu, JAVA_HOME is typically:
export JAVA_HOME=/usr/lib/jvm/java-21-openjdk-amd64

# For CentOS, JAVA_HOME is typically:
export JAVA_HOME=/usr/lib/jvm/jre-21

Note: You’ll update the service file with the correct JAVA_HOME in a later step.

---

Step 3: Prepare the v15 Installation

3.1 Upload and Extract v15 Distribution

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

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

# Extract to /usr/local/ (NOT into the old 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/

3.2 Verify License Key

# Check that LICENSE.KEY exists in the new distribution
ls -la /usr/local/red5pro-server-15.0.0/LICENSE.KEY

# If your license has been updated, ensure it's the correct one
# You can find your license at: https://account.red5.net/overview

---

Step 4: Migrate Configuration Files

IMPORTANT: Do NOT copy configuration files directly from v13 to v15. The structure has changed, especially for SSL configuration. Manually update the new configuration files.

4.1 Migrate red5.properties

The most important configuration file changes between v13 and v15.

# Open both files side-by-side for comparison
# OLD: /usr/local/red5pro/conf/red5.properties
# NEW: /usr/local/red5pro-server-15.0.0/conf/red5.properties

Common settings to migrate:

Ports Configuration

# HTTP
http.host=0.0.0.0
http.port=5080
https.port=443

# RTMP
rtmp.host=0.0.0.0
rtmp.port=1935

# RTMPS (if using)
rtmps.host=0.0.0.0
rtmps.port=8443

SSL Configuration (MAJOR CHANGE in v14+)

v13 SSL Configuration (OLD METHOD – DO NOT USE):

# v13 required editing both red5.properties AND jee-container.xml
rtmps.keystorepass=yourpassword
rtmps.keystorefile=/path/to/keystore.jks
rtmps.truststorepass=yourpassword
rtmps.truststorefile=/path/to/truststore.jks

v15 SSL Configuration (NEW METHOD):

# In red5.properties, add these NEW properties:
secure.enabled=true
websocket.enabled=true

# Keep the existing SSL paths:
rtmps.keystorepass=yourpassword
rtmps.keystorefile=/path/to/keystore.jks
rtmps.truststorepass=yourpassword
rtmps.truststorefile=/path/to/truststore.jks

Note: In v15, you do NOT need to modify jee-container.xml for SSL. The secure.enabled=true property handles this automatically.

Tomcat/HTTP Settings (if customized)

# If you customized these for performance:
http.max_threads=20
http.acceptor_thread_count=10
http.processor_cache=20
http.max_headers_size=8192
http.max_keep_alive_requests=100

4.2 Migrate webrtc-plugin.properties

# Compare and migrate WebRTC settings
sudo diff /usr/local/red5pro/conf/webrtc-plugin.properties 
           /usr/local/red5pro-server-15.0.0/conf/webrtc-plugin.properties

# Common settings to check:
# - ICE server configurations
# - STUN/TURN settings
# - Port ranges
# - Codec preferences

4.3 Migrate network.properties

# If you have forced IP addresses or custom ICE settings
sudo cp /usr/local/red5pro/conf/network.properties /tmp/network.properties.v13

# Manually update the new file:
sudo nano /usr/local/red5pro-server-15.0.0/conf/network.properties

Common settings:

# Forced IP addresses (if needed)
force.public.ip=your-public-ip
force.local.ip=your-private-ip

# Port availability checking (if enabled)
check.port.availability=true

# OpenSSL workaround (if needed)
#crypto.override=SUNJCE

4.4 Migrate cluster.xml (if using clustering)

# If you're using static clustering
sudo cp /usr/local/red5pro/conf/cluster.xml /tmp/cluster.xml.v13

# Manually update the new file:
sudo nano /usr/local/red5pro-server-15.0.0/conf/cluster.xml

Remember: Cluster password cannot contain capital letters.

4.5 Migrate Authentication Configuration

# If using Simple Auth Plugin
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 support is now available in SimpleAuth plugin. See JWT documentation for details.

4.6 Migrate HLS Configuration

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

# Manually apply your customizations to the new file

4.7 Migrate Cloud Storage Settings

# If using cloud storage (S3, Azure, etc.)
sudo cp /usr/local/red5pro/conf/cloudstorage-plugin.properties 
        /usr/local/red5pro-server-15.0.0/conf/cloudstorage-plugin.properties

Improvement in v15: S3 uploads for recordings now retry on failures automatically.

4.8 Migrate API Configuration

# If using the Red5 Pro 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

4.9 Migrate Custom Webapps

# Copy any custom webapps (NOT live, root, api, inspector, streammanager, webrtcexamples)
# Example for a custom webapp named "myapp":
sudo cp -r /usr/local/red5pro/webapps/myapp 
           /usr/local/red5pro-server-15.0.0/webapps/myapp

WARNING: If your custom webapp uses Tomcat-specific features, it may need updates for Tomcat 11 compatibility. See Tomcat Migration Guide.

---

Step 5: Handle RTMPE Deprecation (if applicable)

RTMPE was removed in v14. If you were using RTMPE for secure RTMP streaming, you must migrate to RTMPS.

5.1 Check if RTMPE is Enabled

# In your v13 installation, check if RTMPE is configured
grep -i "rtmpe" /usr/local/red5pro/conf/red5-core.xml

5.2 Migrate to RTMPS

If RTMPE was enabled, you must switch to RTMPS. See SSL Configuration Guide for complete setup instructions.

RTMPS requires:

1. Valid SSL certificate (keystore.jks)
2. Truststore (truststore.jks)
3. Configuration in red5.properties and red5-core.xml

---

Step 6: Update Service Configuration

The systemd service file must be updated for Java 21.

6.1 Update red5pro.service File

# Copy the new service file from the v15 distribution
sudo cp /usr/local/red5pro-server-15.0.0/red5pro.service /tmp/red5pro.service.v15

# Edit it to ensure correct paths
sudo nano /tmp/red5pro.service.v15

Verify these settings in the service file:

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

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

# CRITICAL: Update JAVA_HOME for Java 21
# For Ubuntu:
Environment=JAVA_HOME=/usr/lib/jvm/java-21-openjdk-amd64
# For CentOS:
# Environment=JAVA_HOME=/usr/lib/jvm/jre-21

# Update RED5_HOME to point to the NEW directory (initially)
Environment=RED5_HOME=/usr/local/red5pro-server-15.0.0

# Kill any orphaned CefRenderer processes
ExecStartPre=-/usr/bin/killall -q CefRenderer

# Use full paths
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

6.2 Install the Updated Service File

# Copy to systemd directory
sudo cp /tmp/red5pro.service.v15 /lib/systemd/system/red5pro.service

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

# Reload systemd daemon
sudo systemctl daemon-reload

---

Step 7: Test the v15 Installation

Before switching to the new installation permanently, test that it works.

7.1 Start Red5 Pro v15

# Start the service with the new configuration
sudo systemctl start red5pro

# Watch the logs for any errors
sudo tail -f /usr/local/red5pro-server-15.0.0/log/red5.log

7.2 Verify Startup

Check that Red5 Pro v15 started successfully:

# Check service status
sudo systemctl status red5pro

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

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

7.3 Verify via Web Browser

1. Open a web browser
2. Navigate to http://your-server-ip:5080
3. Verify the version number shows 15.0.0 in the top-left corner
4. You should see the Red5 Pro welcome page

7.4 Test WebRTC (if using SSL)

If you’re using WebRTC with SSL:

1. Navigate to https://your-domain:443/webrtcexamples/
2. Try publishing a test stream
3. Try subscribing to the test stream
4. Verify audio/video works correctly

7.5 Test RTMP Publishing

# Using ffmpeg (if installed)
ffmpeg -re -i test.mp4 -c:v copy -c:a copy -f flv rtmp://your-server:1935/live/test

# Then subscribe to stream "test" via webrtcexamples or another client

7.6 Check Logs for Errors

# Look for any ERROR or WARN messages
grep -i "error|warn" /usr/local/red5pro-server-15.0.0/log/red5.log | tail -50

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

---

Step 8: Finalize the Upgrade

Once testing is successful, finalize the upgrade.

8.1 Stop the v15 Service

sudo systemctl stop red5pro

8.2 Switch to the Final Directory Structure

# Rename the old v13 directory
sudo mv /usr/local/red5pro /usr/local/red5pro-v13-old

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

8.3 Update Service File Paths

# Edit the service file to use the standard /usr/local/red5pro path
sudo nano /lib/systemd/system/red5pro.service

Change:

Environment=RED5_HOME=/usr/local/red5pro-server-15.0.0
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

To:

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

8.4 Reload and Enable Service

# Reload systemd daemon
sudo systemctl daemon-reload

# Enable service to start on boot
sudo systemctl enable red5pro.service

# Start the service
sudo systemctl start red5pro

# Verify it's running
sudo systemctl status red5pro

8.5 Final Verification

# Verify version
curl -s http://localhost:5080 | grep -i "version" || echo "Check in browser"

# Check service is enabled
sudo systemctl is-enabled red5pro

# Verify it survives a reboot (optional)
sudo reboot
# After reboot:
sudo systemctl status red5pro

---

Step 9: Post-Upgrade Tasks

9.1 Monitor Performance

Monitor your server for the first 24-48 hours after upgrade:

# Watch resource usage
htop

# Monitor Red5 Pro logs
sudo tail -f /usr/local/red5pro/log/red5.log

# Check for any unusual errors
sudo journalctl -u red5pro -f

9.2 Update Monitoring/Alerts

If you have monitoring systems, update them to expect:

• Java 21 processes (not Java 11)
• New log patterns from v15
• Updated version strings in health checks

9.3 Update Client Applications

Inform your development team about new features in v15:

• Conference API in Stream Manager (if using SM 2.0)
• SRT egress support for new streaming workflows
• JWT support in SimpleAuth for enhanced security
• Mixer image overlays for advanced mixing scenarios
• Improved Facebook Social Pusher reliability

9.4 Test Custom Plugins (if applicable)

If you have custom Java plugins:

# Check plugin logs for compatibility issues
grep -i "plugin" /usr/local/red5pro/log/red5.log

# Look for ClassLoader or NoClassDefFoundError exceptions
grep -i "classloader|noclassdef" /usr/local/red5pro/log/red5.log

If plugins fail, they may need to be recompiled for JDK 21. See Detecting Compatibility Issues with JDK21.

9.5 Clean Up Old Installation (Optional)

After confirming v15 is stable for 7+ days:

# Remove the old v13 installation
sudo rm -rf /usr/local/red5pro-v13-old

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

---

Rollback Procedure

If you encounter critical issues, you can rollback to v13.

Rollback Steps

# 1. Stop the v15 service
sudo systemctl stop red5pro

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

# 3. Update service file to use Java 11
sudo nano /lib/systemd/system/red5pro.service
# Change JAVA_HOME back to Java 11 path:
# Environment=JAVA_HOME=/usr/lib/jvm/java-11-openjdk-amd64

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

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

---

Troubleshooting

Issue: Service Fails to Start

Symptoms:

sudo systemctl status red5pro
# Shows "failed" or "inactive"

Solution:

# Check detailed error messages
sudo journalctl -u red5pro -n 100 --no-pager

# Common issues:
# 1. Wrong JAVA_HOME path
# 2. Permission issues
# 3. Port already in use
# 4. Configuration syntax errors

# Verify JAVA_HOME
echo $JAVA_HOME
ls -la $JAVA_HOME/bin/java

# Check port availability
sudo netstat -tulpn | grep ':5080|:1935'

# Test configuration files
grep -i "error" /usr/local/red5pro/log/red5.log

Issue: WebRTC Not Working After Upgrade

Symptoms: Publishing/subscribing fails with ICE errors

Solution:

# 1. Verify SSL configuration (WebRTC requires SSL)
grep -i "secure.enabled|websocket.enabled" /usr/local/red5pro/conf/red5.properties
# Should show:
# secure.enabled=true
# websocket.enabled=true

# 2. Verify keystore/truststore paths
ls -la /etc/letsencrypt/live/your-domain/keystore.jks
ls -la /etc/letsencrypt/live/your-domain/truststore.jks

# 3. Check WebRTC plugin is loaded
grep -i "webrtc" /usr/local/red5pro/log/red5.log | grep -i "loaded|started"

# 4. Verify forced IPs if needed
grep -i "force." /usr/local/red5pro/conf/network.properties

Issue: Custom Webapp Not Loading

Symptoms: Custom webapp shows 404 or fails to load

Solution:

# Check if webapp was copied
ls -la /usr/local/red5pro/webapps/your-custom-app/

# Check for Tomcat 11 compatibility issues
grep -i "servlet" /usr/local/red5pro/log/red5.log

# Your webapp may need updates for Tomcat 11
# See: https://tomcat.apache.org/migration.html

Issue: High CPU/Memory Usage

Symptoms: Server performance degraded after upgrade

Solution:

# 1. Check Java heap settings
ps aux | grep red5 | grep Xmx

# 2. Review optimization guide
# See: /docs/red5-pro/users-guide/optimization/red5-pro-server-optimization/

# 3. Ensure file limits are set correctly
ulimit -n
# Should show 1000000

# 4. Check for memory leaks
# Monitor for 24 hours and check if memory grows continuously

Issue: RTMPS Connections Failing

Symptoms: RTMPS streams fail after upgrade (if you migrated from RTMPE)

Solution:

# 1. Verify RTMPS is enabled in red5-core.xml
grep -A 10 "rtmpsMinaIoHandler" /usr/local/red5pro/conf/red5-core.xml
# Should be uncommented

# 2. Verify RTMPS port in red5.properties
grep "rtmps.port" /usr/local/red5pro/conf/red5.properties

# 3. Test RTMPS connection
# Use SSL-enabled RTMP client to connect to rtmps://your-server:8443/live/test

---

Additional Resources

• Red5 Pro v15.0.0 Release Notes
• Red5 Pro v14.0.0 Release Notes
• SSL Configuration Guide
• Server Optimization Guide
• Tomcat 11 Migration Guide
• JDK 21 Compatibility Tool

---

Support

If you encounter issues during the upgrade process:

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