Nimble Streamer configuration

Nimble Streamer general settings are stored in /etc/nimble/nimble.conf file.

Nimble's parameters are either mandatory and included in default setup or optional and may be set up for some features and improvements.


Important
: to apply config changes, please re-start Nimble instance by running:
sudo service nimble restart

Mandatory parameters 


Those parameters are set during installation and initial setup.
  • port contains port number which Nimble is listening to. Default value is 8081. You may also specify several ports separated by comma (e.g. port = 80, 8081). See also listen_interfaces parameter below.
  • worker_threads is a number of threads used for processing incoming requests. Default is 1.
  • max_cache_size is a maximum size of RAM data cache in megabytes. It's 64 MB by default.
  • cache_path is a path to the disk cache storage, with default value /var/cache/nimble.
  • max_disk_cache_size is a size of file cache measured in Mb, the default value is 4096 MB.
  • panel_domain and panel_port contain URL and port used for syncing with WMSPanel.
  • panel_uuid and panel_password has credentials for safe communication with WMSPanel.
  • logging is used for getting information about what happens inside of Nimble.

For logging, you may use both Nimble log files and syslog. Possible values for both types are errorinfoverbose and debug. The syntax is
logging = file:<value>, syslog:<error>
or
logging = <value>, syslog:<value>
Examples:
logging = info, syslog:error
logging = info, syslog:info
logging = file:info, syslog:error
Please also check access logs section below.

Optional parameters


Each of the parameters below are set up for additional features and improvements.

You may control a maximum life time of VOD disk cache chunks via vod_cache_timeout parameter. The default value is 1 hour so the chunks are stored for an hour after the last request. If you want chunks to be stored for 2 days, just set up this:
vod_cache_timeout = 48
If you need your disk cache to be cleaned up after some minimum amount of time using LRU approach, use vod_cache_min_storage_time parameter which specifies amount of hours for cached item, 1 is the default value. Check VOD cache usage details for more information. If you need LRU time to be set to 2 hours, set it up like this:
vod_cache_min_storage_time = 2
Both vod_cache_timeout and vod_cache_min_storage_time parameters support several measurement units like 10s, 10m, 10h which stand for seconds, minutes and hours respectively. If they are not specified, then hour is the default unit.

In some cases an admin needs to set chunk duration different from default value. This is what vod_chunk_duration parameter is for. You may set amount of seconds for VOD chunks from 1 to 50. Example:
vod_chunk_duration = 3
If you'd like to use RAM cache prior to disk cache, use this parameter:
vod_to_ram_cache_first = true
In this case RAM cache will be used until it's full.

To specify how much RAM may be used fo VOD cache, use ram_cache_for_vod_threshold parameter. E.g. 0.5 means 50%:
ram_cache_for_vod_threshold = 0.5
By default, it's 0.8.

When streaming VOD HLS, you may need to specify an exact video and/or audio track to use for playback. Nimble Streamer supports MP4 tracks selection for HLS and you may use nimble_video_index and nimble_audio_index parameters for it. If you need to use other parameters' name, please use the following config entries:
nimble_video_index = <name for video>
nimble_audio_index = <name for audio>
E.g.
nimble_audio_index = audioIndex
If you use SRT or WebVTT subtitles file for a VOD file and would like to define default language, use "vod_subtitle_default_language_id" parameter with alpha3 code like this:
vod_subtitle_default_language_id = fra
Read more about VOD subtitles support in Nimble Streamer.


If your media is audio-only, Nimble Streamer produces audio-only HLS with significantly reduced size. However some players require MPEG-TS chunks, e.g. old STBs etc. So we added the following parameter to generate VOD HLS with MPEG-TS chunks.
mpegts_for_audio_vod = true
The mode is created specifically for the mentioned scenario only. In all other cases, this option works the same as default "HLS" option.

By default, Nimble Streamer sets Cache-Control header for playlists and chunks to "no-cache". To change this behavior, use playlist_cache_control and chunk_cache_control parameters and set proper value for it. E.g.
playlist_cache_control = max-age=30
chunk_cache_control = max-age=120
will set 30 seconds as maximum age for playlists cache and 120 seconds for chunks.

There are cases when Nimble Streamer is placed behind the reverse proxy. This is usually done for security reasons. To get IP address of end user for geo stats and hotlinking protection, Nimble needs to process X-Forwarded-For HTTP header for incoming connection. To make it work, you need to add the following parameter.
cdn_origin = true

You may also change Nimble Streamer user agent name for accessing origin server when working as re-streaming edge. Just add this string in the config file:
user_agent = User-Agent-Name

By default, Nimble Streamer listens for incoming client request via the port specified by port parameter on all available interfaces. You may specify exact interfaces to listen at via the listen_interfaces parameter.
listen_interfaces = 127.0.0.1, 172.16.1.9
The default value is plain "listen_interfaces = *".

enable_ipv6 parameter makes Nimble Streamer to support IPv6
enable_ipv6 = true

By default Nimble Streamer checks user session ID against his IP address to avoid fraud. If this needs to be overlapped for telecom-related reasons, you can disable it by setting up this parameter:
restrict_session_ip = false
This will make Nimble skip IP address check for each session. Read the following HLS metrics calculation article for detailed description of this use case among other.

Each streaming session has its ID to handle precise stats calculation and other related capabilities. The default timeout for expiring session IDs is 1 hour, but it is possible to change it using "session_timeout" variable in nimble.conf, e.g.
session_timeout = 60
The value is set in minutes.

When re-streaming content, you may need to pass through headers from player to origin server. Nimble can make a pass-through along with adding headers' prefixes.
To enabled this, add this option:
pass_headers = true
The default prefix is "X-Peer-Header-". If you need to change that, use "passed_header_prefix" parameter:
passed_header_prefix = X-Passthru-

Some scenarios require using absolute paths in playlists and chunk lists, especially when using load balancing techniques. This is what absolute_path parameter is for
absolute_path = <IP>:<port>
If your port is 80 then you may skip :<port> part.

A few parameters about CORS. Several players may require Access-Control-* headers in server responses for controlling cross-origin resources sharing. Use the following parameters for that:

access_control_allow_origin = <some value>
access_control_allow_credentials = <some value>
access_control_expose_headers = <content-length>
access_control_allow_headers = <some value>
Some of possible values are
access_control_allow_origin = *
access_control_allow_credentials = true
access_control_allow_headers = Range
and so on.
Also, some streamer may need to define crossdomain.xml content. Use the following parameter to specify the domain within the XML file which is going to be sent from Nimble Streamer:
crossdomain_xml_allow_access_from_domain = <your.domain>
E.g. crossdomain_xml_allow_access_from_domain = wmspanel.com
You may also define and return an entire file using crossdomain_xml parrameter:
crossdomain_xml = /etc/nimble/crossdomain.xml
Read this CORS-related article for details regarding cross-domain policy.


If you use Nimble Streamer geo-location balancing or WMSAuth geo-location restriction you may set up your Nimble instance to automatically update geo-location database. Just put this parameter into your config:
update_geoip_database = true
Nimble will be checking and updating the geo base once a day.


Some customers need access logs for further analysis besides using WMSPanel reporting. A few parameters can be used for that purpose.
log_access = file, syslog
log_access enables access log which would have IP, time and full URL of the requested stream. You may use them in any combinations, e.g. specify only syslog.
Besides connections stats, you can log session the same way.
log_sessions = true, syslog
Log files will be rotated, i.e. you can define max size of each log file and their maximum number.
max_log_file_size
This is the amount of MBs for each log file in rotation.
max_log_files_to_keep
This is the number of log files being kept in rotation.

If you need to handle progressive download or re-streaming for any extension other then the extension supported by default, you can use this parameter:
custom_pd_exts = <list>
E.g. "custom_pd_exts = nff,ts" to support .NFF and .TS

If you process MPEG2TS streams, you may need to set inactivity check interval.
mpegts_inactivity_check_interval = <minutes>
mpegts_inactivity_check_interval = 20 mean stream will be restarted after 3 * mpegts_inactivity_check_interval = 60 seconds.
The problem is in fact sometimes your mpeg2ts streams stop sending data for some period and then start again. This period may be more than default 15 seconds, hence the separate parameter for controlling it.

In case of large bitrate streams through UDP via MPEG-TS or RTSP, some customers see artifacts or video freeze. This is described in this FAQ post. This parameter should help:
udp_so_receive_buffer = <UDP buffer in bytes>
In some high loaded systems the number of simultaneous RTMP connection can be significant. By default Nimble processes 2500 simultaneous connection per each rtmp working thread, but you can increase/decrease this value with the following parameter:
rtmp_max_viewers = <viewers count>
You can control rtmp working thread count. By default Nimble set this value to 4. You can change this value with the following parameter:

        rtmp_working_thread = <working threads>

If you use pull by request with RTMP, you may change the buffer on origin to improve playback experience on edge.
rtmp_buffer_items = <buffer_size>
Read this article for details.


transmuxer_threads parameter sets a number of threads used for processing VOD HLS/MPEG-DASH transmuxing requests. Use it in case you have a high load use cases.
transmuxer_threads = <threads count>

If you need to enable EXT-X-PROGRAM-DATE-TIME field for your live HLS streams, you need to set this parameter:
hls_add_program_date_time = true

A few parameters are available to adjust SLDP support in Nimble Streamer.
Maximum SLDP clients per working thread are set by this:
websocket_live_max_viewers = <working threads>
It's 2500 by default.

SLDP workers count is set here.
websocket_live_worker_threads = <workers count>
It's 1 worker by default.


Important: to apply config changes, please re-start Nimble instance by running:
sudo service nimble restart


Nimble Streamer has status API for accessing some basic server metrics in real-time. Read this description to see what config parameters changes are needed for that.

Additional configuration options of Nimble Streamer can be found in this article.

If you have any questions or issues regarding Nimble Streamer usage and configuration, feel free to contact us any time.

8 comments:

  1. Could you update this doc to include the default vod_cache_min_storage_time of 3600 seconds (1 hour)?

    ReplyDelete
  2. thanks, we've fixed article according to your feedback !

    ReplyDelete
  3. Hello, I've experienced lots of feezing when adding these configurations.. once i remove them it goes normally.. I need this because CDN then wont work by cache then as it takes the origin as mandatory..
    max_cache_size = 6144
    vod_to_ram_cache_first = true
    chunk_cache_control = max-age=120
    playlist_cache_control = max-age=30

    ReplyDelete
    Replies
    1. Hello,

      We can see you've posted this to our helpdesk. Thanks for the follow up - we'll respond there with details.

      Delete
  4. ncie very helpful posts and comments nice and keep it up...

    ReplyDelete
  5. Hello, how many users I can have in one server with nimble?
    RTMP
    HLS
    Dash?

    ReplyDelete
  6. Hi,
    it's too general questions and numbers depends on so many factors so I cannot answer it exactly. There are several but not all:
    - stream bandwidth
    - server available bandwidth
    - server cpu power/ram etc
    - clients location related to your server
    - and many many others

    You can expect Nimble will do the best. But we would recommend to test it.

    ReplyDelete