December 30, 2015

RTSP and RTMP publish control setup

Previously our team introduced Publish control framework to allow applying our customers' business logic to incoming streams by defining multi-level authorization.

This article describes publish control setup process from deployment point of view. Take a look at the picture below to overview available scenarios and let's go through them step-by-step.

Start publishing

We won't consider a case when you don't need any protection for incoming RTSP and RTMP streams, as you can just specify only RTSP or RTMP port number. Any publishers can push any streams to your server through the specified port so we do not recommend it.

To start implementing multi-level protection with Nimble Streamer you need to use publishing credentials. You specify a unique username and password for a separate application which will be used for accepting published RTSP and RTMP streams.

Publishing applications list.
New publishing application.

Using publish signature

Now we'll start setting up publish control framework. This type of protection requires a publish signature to be added to the connection URI used for RTSP or RTMP streaming from the source.

The signature is based on the following parameters:
  • user identifier (ID);
  • stream name;
  • password which was specified in application;
  • publisher IP address (optional).
You need to specify an application in WMSPanel control UI to operate the incoming streams the publishing users will be grouped in. The application name should be the same as specified on "Start publishing" step. The password which is used in this signature should be specified in the publish control application settings via the UI.

Empty applications list for further publish control.
New publish control app setting.
New app in the list.

To publish to Nimble Streamer, the publisher will use the URL like this:
For RTMP it will be

Here, a publishsign is the signature for incoming RTSP or RTMP stream.

Check an example of code for generating a signature in our github repo.

The signature is added in URI either manually or via your own application business logic, this is up to a developer to decide on that.

When the user starts publishing RTSP or RTMP stream, the media server will check publish signature and if this signature does not match the calculated signature, then the user stream will not pass.
At this step the publish control is very similar to the hotlinking protection.

Using publish authorization handler

You can get further control of the incoming streams during connection time. For this case you need to create a handler application and specify its URL in the control UI in "Control" -> "Publish control" menu.

The handler is an HTTP controller which is able to process POST requests and return the response according to your business logic. If you don't specify the handler URL then Publish control framework will not try to call the handler. This is done to allow debugging the signature-checking mechanism described above.

Publish control handler URL setup.
Besides handler URL, you can set up the grouping interval for the incoming streams. The handler is called with some timeout to aggregate several requests in one. This allows avoiding the resources waste in case of frequent calls.

Nimble publish control passes the client signature to the handler. As a response to the request, the handler must return the status and Nimble Streamer acts accordingly to allow or deny the connection, based on the status received from the handler.

The sample code of the handler is available in our github repo. It takes the call from Nimble and returns proper response. The call is a POST request with "Content-type" field of "application/json".

Here's an example of request:
{"PublishAuthRequest":[{"seq":"1", "id":"ID_1", "ip":"","stream":"live/stream"},{"seq":"2", "id":"ID_2","ip":"","stream":"live/stream2"}]}
Here you can see the following fields.

  • seq - a sequence number, which is serial number of an entry; it will be used in a response.
  • id - publisher ID within your business logic; each publisher may use several devices while having same user account so this field may be useful for block duplicate streams as example.
  • ip - the IP address of the publisher.
  • stream - the URI of the stream which is being published.

A response will contain statuses of each sequence - either success or fail. Here is an example:
{"PublishAuthResponse":[{"seq":"1", "status":"success"},{"seq":"2", "status":"fail"}]}

You also noticed the "Allow by default" check box in application settings on "Using publish signature" step. If the handler in not available or sequence number is not specified, and this checkbox is turned on, then incoming streams will not be blocked. If it's unchecked then the stream is blocked.

Controlling streaming process

With publish control you can manipulate RTSP and RTMP streams not only at connection time, but also during the streaming process as well when the user is already connected and streaming. To use this capability, you need to create a controller which will request Nimble with any frequency to identify which users still publish their streams. If you need to stop certain streaming session then this controller calls Nimble, specifies the session key and this stream will be blocked immediately.

1. Working with Nimble API

All operations described below are made via Nimble Streamer control API. Please refer to the reference to see how it can be used. First of all, please check how to enable API. You may also want to make authorized requests.

When API is enabled, you can start working with it from your controller. There are two steps to deny unwanted sessions from publishing. First one is to get list of sessions and the second one is to send list of blocked sessions.

2. Request sessions from Nimble

To get info about all current published streams you need to call the following method via GET request
Here is how Nimble Streamer responds with sessions IDs.
{"PublishControlStatus":[{"key":"1", "id":"ID_1", "ip":"","stream":"live/stream"}, {"key":"2", "id":"ID_2", "ip":"","stream":"live/stream2"}]}
Here are the response fields:
  • key - session key.
  • id - publisher ID within your business logic.
  • ip - the IP address of the publisher.
  • stream - the URI of the stream which is being published.
With that information you can now make decisions about denying some streams.

3. Block designated sessions

Now you need to call Nimble API with list of blocked sessions. It's a POST request to the following URI:
The body of this message will contain the list of denied sessions, like this:
{"PublishControlDenyRequest":["1", "2"]}
Here, 1 and 2 are the session key. The response is from Nimble would be:
Now those sessions are blocked.

Notice that all mentioned code samples are available in our github repo.

Overall, the described methods allows obtaining full control over the RTSP and RTMP streams publication process for your infrastructure. This allows building streaming solutions with any business logic.

If you need to change the incoming streams' content parameters, like change the bitrate, use our Live Transcoder for Nimble Streamer to transform. It has high performance and low resource usage.
Please contact our helpdesk if you have any questions regarding the described functionality.

Related documentation

No comments:

Post a Comment