This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

Installation

Installing and running ew-npvr

Installation

The ew-npvr service is distributed as a CentOS/Red Hat RPM and is available as ew-npvr.service when installed. It works on Red Hat 8 and compatible versions.

To install version x.y.z, the rpm command can be used as follows:

dnf install ./ew-npvr-x.y.z-1.el8.x86_64.rpm

The service can be controlled with the standard systemctl commands:

systemctl start ew-npvr
systemctl stop ew-npvr
systemctl status ew-npvr

Logs from the service can be seen using journalctl -u ew-npvr.

The unit file is available in /usr/lib/systemd/system/ew-npvr.service.

When run as a service, ew-npvr reads its initial configuration from the AgileTV Origin configuration system.

To uninstall the service, do:

dnf remove ew-npvr

When uninstalling it is recommended to first stop the service.

Prerequisites

Before installing ew-npvr, ensure the following prerequisites are met:

  1. Database (Optional): PostgreSQL database server accessible from the ew-npvr host
    • Required for management API functionality
    • Not required if only using media streaming API
  2. Storage: Sufficient disk space for NPVR recordings at configured storage locations
  3. Live Ingest: AgileTV Origin live ingest service (ESB3003) if recording live channels
  4. Network: Network connectivity to database and channel sources

Note: The service operates in degraded mode if the database is unavailable - the media API will continue to function for streaming existing content, but the management API will not be available for creating or managing recordings.

Directory Structure

After installation, the following directories are created:

  • /var/log/edgeware/ew-npvr/: Log files directory
    • ew-npvr.log: General service logs
    • ew-npvr-streaming.log: Media streaming logs
    • ew-npvr-admin.log: Administration API logs
  • /var/run/edgeware/ew-npvr/: Runtime files (Unix sockets)
  • /etc/edgeware/ew-npvr/: Configuration files

Initial Setup

  1. Configure the database connection in the AgileTV Origin configuration
  2. Set up NPVR storage locations
  3. Configure live ingest channels for NPVR integration
  4. Start the service: systemctl start ew-npvr
  5. Verify the service is running: systemctl status ew-npvr

Command Line Options

The ew-npvr service supports the following command-line options:

  • --print-schema: Print the embedded JSON schema for configuration and exit
  • --management-address <address>: Address for management API server (default: 0.0.0.0:8099)
  • --media-address <address>: Address for media API server (default: unix:///var/run/edgeware/ew-npvr/sock.sock)
    • Supports both TCP addresses (e.g., 0.0.0.0:8080) and Unix sockets (e.g., unix:///var/run/edgeware/ew-npvr/sock.sock)
  • --content-info-cache-size <size>: Maximum number of entries in content info cache (default: 1000, range: 1-65536)
  • --write-rate-limit <bytes>: Write rate limit in bytes per second when copying files (default: 0 = no limit)
    • Use this to prevent storage I/O saturation during recording operations
    • Example: --write-rate-limit 104857600 limits writes to 100 MB/s

These options can be configured in the systemd service file at /usr/lib/systemd/system/ew-npvr.service.

Accessing API Documentation

Once the service is running, Swagger API documentation is available at:

http://<management-address>/swagger/

For example, with default settings:

http://localhost:8099/swagger/

1 - Upgrades

Upgrading ew-npvr to newer versions

Upgrade Process

Standard Upgrade

To upgrade ew-npvr to a new version, follow these steps:

  1. Stop the service:

    systemctl stop ew-npvr

  2. Install the new version:

    dnf upgrade ./ew-npvr-x.y.z-1.el8.x86_64.rpm

  3. Review configuration changes:

  4. Start the service:

    systemctl start ew-npvr

  5. Verify the upgrade:

    systemctl status ew-npvr
journalctl -u ew-npvr -n 50

Database Schema Upgrades

Database schema migrations are handled automatically by the service on startup. When upgrading:

  1. Ensure database connection is configured and accessible
  2. The service will apply any necessary schema migrations on first start
  3. Monitor logs for migration status: journalctl -u ew-npvr -f

Backup Recommendation: Before upgrading, backup your PostgreSQL database:

pg_dump -h localhost -U npvr_user npvr_db > npvr_backup_$(date +%Y%m%d).sql

Rolling Back

If you need to roll back to a previous version:

  1. Stop the service:

    systemctl stop ew-npvr

  2. Downgrade the package:

    dnf downgrade ew-npvr-<previous-version>

  3. Restore database if needed:

    # Only if database schema changed
psql -h localhost -U npvr_user npvr_db < npvr_backup_YYYYMMDD.sql

  4. Start the service:

    systemctl start ew-npvr

Compatibility Notes

  • Database: Schema changes are forward-compatible but not backward-compatible. Always backup before upgrading.
  • Configuration: New configuration options have default values, so existing configurations remain valid.
  • API: The Management API maintains backward compatibility within major versions.
  • Storage: Recording storage format is backward-compatible.

Testing the Upgrade

After upgrading, verify functionality:

  1. Check service health:

    curl http://localhost:8099/

  2. List existing recordings:

    curl http://localhost:8099/api/v1/content?limit=10

  3. Create a test recording:

    curl -X POST http://localhost:8099/api/v1/content \
  -H "Content-Type: application/json" \
  -d '{
    "channelName": "test-channel",
    "title": "Upgrade Test",
    "startTime": '$(date +%s)',
    "stopTime": '$(( $(date +%s) + 3600 ))'
  }'

  4. Verify logs:

    journalctl -u ew-npvr -n 100 --no-pager

Common Upgrade Issues

Service fails to start:

  • Check logs: journalctl -u ew-npvr -n 50
  • Verify configuration syntax
  • Check file permissions
  • Ensure database is accessible

Database migration fails:

  • Check PostgreSQL connectivity
  • Verify user has schema modification permissions
  • Review migration logs in service output
  • Consider restoring backup and retrying

Recordings not accessible:

  • Verify storage paths haven’t changed
  • Check file permissions on storage locations
  • Review configuration for storage location names
  • Ensure media API is properly configured

Performance degradation:

  • Check content info cache size setting
  • Review write rate limit if enabled
  • Monitor database query performance
  • Verify disk I/O isn’t saturated

Version-Specific Notes

Check the release notes for version-specific upgrade instructions and breaking changes.