July 8, 2013

Nimble configs explained


UPDATE: General server setting file description was moved to this article.

Our team develops Nimble Streamer to be available free of charge.

This means that anyone may install Nimble Streamer from our repository and keep using it manually, without our service. Of course, the best user experience is achieved via our excellent WMSPanel reporting and control panel but it's up to a user to decide whether he wants to pay for comfort or he needs more financial flexibility.

The key element of "non-service" usage of Nimble Streamer is the ability to configure the server manually via configuration files. To change the Nimble behavior, you need to change the configs. WMSPanel does this remotely, you can do it yourself. Knowing configs structure allows doing manual changes without WMSPanel. This also brings an ability to make custom automated configuration of server network in case of complex deployments.

So let's see configuration files structure.

General settings


Server general settings are stored in /etc/nimble/nimble.conf file.

Read this config file description to learn more about how to control Nimble behavior and attributes.

Also, take a look at performance tuning guide to see how much your hardware can handle with best settings of Nimble Streamer.

Routes settings


Routes settings are stored in /etc/nimble/rules.conf.

UPDATE: This description is outdated. We recommend using WMSPanel for primary setup in order to see how parameters and their values are mentioned in config.

The typical routes settings config is listed below. It's a JSON-formatted data set. The example below is formatted for educational purposes, the real config is presented as a single line.
/* please do not modify this file, all changes will be overwritten by wmspanel agent */
{"SyncResponse":
  {
    "status":"success",
    "RoutesHash":1373269971,
    "Users":0,
    "Routes":
    [
      ["","/local/raw/","file:///var/www/content/raw/",""],
      ["streamingtestingserver.com:8080","/live/", "live.nimblestreamer.com:8080","/"],
      ["GEO_R_AQ","","live2.nimblestreamer.com",""],
      ["GEO_R_IP_R_Range 2","","test.nimblestreamer.com",""]
    ],
    "IpRanges":
    [
      ["IP_R_Range 1","192.168.0.0/22"],
      ["IP_R_Range 2","172.168.0.0/24"],
      ["IP_R_LocalHostRange","127.0.0.0/8,128.0.0.0/8"],
      ["IP_R_all","0.0.0.0/0"]
    ]
  }
}

The first comment line warns you that routes settings are replaced after the next time you change settings within the panel. If you don't want the settings to be replaced, just remove the server from the panel or make its backup.

First 3 parameters - status, routeHash and Users - are used for syncing purposes so you don't need to change them.

Next sections is Routes, it contains the routes defined within a panel. Each entry separated by [ and ] is a set of 4 strings. They are Domain From, Path From, Domain To and Path To respectively.

For progressive download or HLS re-streaming set up those 4 elements work straight-forward, please read this or this post for set up details.

For geo forwarding see route 3. The first element stands for country of original request made by "GEO_R_" prefix and ISO country codes. In this example we see "GEO_R_AQ" having "AQ" country code meaning Afganistan. Path From and Path To are blank, with only Domain To pointing to the domain and port of destination of request.

For IP range forwarding you can check route 4. It has the same "GEO_R_" prefix followed by the name of IP range. All names of IP ranges are defined within WMSPanel and synced in this config as well. Let's take a look at IpRanges section. Each entry has its name used in WMSPanel and in the routes above. It also has CIDR defining the range itself. So having list of ranges you can use them in any of your routes.

Those are all parameters you may need for controlling server behavior. Once you make a change please re-start Nimble by running
sudo service nimble restart

Nimble Streamer feature set will be extended further and its configuration files will also be changing. Our team will be updating this description to keep it up-to-date with latest releases.

You can try Nimble Streamer any time and contact us in case of any questions. We're looking forward to your questions and suggestions.

Nimble Streamer automation example


Let's see how to automate Nimble installation and set up in 2 easy steps. Let's take Ubuntu as example while you can use a variety of other Linux distributions.

1. Install Nimble Streamer


Add new repository for Nimble Streamer package installation and update repositories:
echo "deb http://nimblestreamer.com/ubuntu precise/" >> /etc/apt/sources.list
apt-get update
apt-get install nimble

2. Configure Nimble Streamer


Create the content directory and point Nimble to take video from there for VOD streaming:
mkdir -p /var/www/video/
echo ‘{"SyncResponse":{"Routes":[["","/vod/","file:///var/www/video/",""]]}}’ > /etc/nimble/rules.conf
service nimble restart
The media is now available at http://<server ip>:8081/vod/ and you can stream it via HLS with URL like this:
http://127.0.0.1:8081/vod/sample.mp4/playlist.m3u8

Please also take a look at Nimble Streamer presentation with server functionality overview and link in "Related documentation" section below.

You can read "The Paranoid’s Guide to Internet Video Streaming" by Thomas Gires to see real-life example of using pay-per-view feature set along with Nimble Streamer as light-weight edge for HLS re-streaming.

You may also consider WMSPanel server tasks remote management via web console for convenient control of server-side commands. Launch any command, like ffmpeg process, with no need to log in via SSH, just an easy-to-use web interface.


Related documentation


Nimble Streamer, Live Streaming via Nimble, Live Transcoder

5 comments:

  1. Hi,

    Can we modify the file /etc/nimble/rules.conf on the fly and apply it on the fly without disconnecting the current streams? It's what the WMSPanel seems to do : the Nimble fetchs configuration modifications and apply them without restarting/disconnecting the current streams.
    How to do it without the WMSPanel and without the restart? (force-reload seems to disconnect too)
    Thanks & Regards
    Edouard

    ReplyDelete
    Replies
    1. At the moment we don't provide functionality for seamless reload of config without WMSPanel.

      Delete
  2. Hi!

    How can I get specification for rules.conf ?

    ReplyDelete
    Replies
    1. We don't have it at the moment as it's being changed and updated all the time. You can register server in the panel, set it up and then see what you have in the config to get the idea of its format.

      Delete