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. We'll overview available scenarios and let's go through them step-by-step.
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, RTMP and WebRTC streams.
The SRT receiver working in Listen mode needs to be set up a bit differently, please check Setting SRT user and password authentication with SRT PASSet article for setup details.
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:
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 application 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.
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:
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.
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 app 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.
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 application. 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.
To get info about all current published streams you need to call the following method via GET request from your controller app:
Now you need to call Nimble API with list of blocked sessions. It's a POST request to the following URI:
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.
This article describes publish control setup process from deployment point of view. We'll overview available scenarios and let's go through them step-by-step.
1. Set up publishing
1.1 Setup for RTMP, RTSP and WebRTC
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, RTMP and WebRTC streams.
 |
| Publishing applications list. |
 |
| New publishing application. |
1.2 Setup for SRT
The SRT receiver working in Listen mode needs to be set up a bit differently, please check Setting SRT user and password authentication with SRT PASSet article for setup details.
2. 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);
- application name and stream name;
- password which was specified in application;
- publisher IP address (optional).
 |
| 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 SRT you will define publisher as show in the following example:
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 the 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.
rtsp://192.168.1.1:554/publish/stream?publishsign=aWQ9SURfMSZzaWduPW95Zi9YVHBLM0c3QkQ4SmpwVnF1VHc9PSZpcD0xMjcuMC4wLjE=For RTMP it will be:
rtmp://192.168.5.5:1935/publish?publishsign=aWQ9SURfMSZzaWduPW95Zi9YVHBLM0c3QkQ4SmpwVnF1VHc9PSZpcD0xMjcuMC4wLjE=/stream
For SRT you will define publisher as show in the following example:
ffmpeg -re -i video.mp4 -codec copy -f mpegts pipe:1 | ./srt-live-transmit -v file://con "srt://127.0.0.1:2020?streamid=/live/srtstream?publishsign=aWQ9SURfMSZzaWduPVQ3SzVlMkMySlRxRExmSTdybVdibVE9PSZpcD0xMjcuMC4wLjE="
For WebRTC it will be:
https://your_host/live/whip?publishsign=aWQ9SURfMSZzaWduPW95Zi9YVHBLM0c3QkQ4SmpwVnF1VHc9PSZpcD0xMjcuMC4wLjE=
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 the 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.
Signature-free mode
You may skip the signature in case you handle your authorization in some other way. Click the "Signature-free mode" checkbox in "Add application settings" dialog (see screenshot above) to disable the signature check described above.
3. 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 application 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.
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":"192.168.1.1","stream":"publish/stream"},{"seq":"2", "id":"ID_2","ip":"192.168.1.2","stream":"publish/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.
4. 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 app 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.
4.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 application. 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.
4.2 Request sessions from Nimble
To get info about all current published streams you need to call the following method via GET request from your controller app:
/manage/publish_control/statusHere is how Nimble Streamer responds with sessions IDs.
{"PublishControlStatus":[{"key":"1", "id":"ID_1", "ip":"192.168.1.1","stream":"publish/stream"}, {"key":"2", "id":"ID_2", "ip":"192.168.1.2","stream":"publish/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.
4.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:
/manage/publish_control/denyThe 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:
{"PublishControlDenyResponse":{"status":"success"}Now those sessions are blocked.
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.
No comments:
Post a Comment
If you face any specific issue or want to ask some question to our team,
PLEASE USE OUR HELPDESK
This will give much faster and precise response.
Thank you.
Note: Only a member of this blog may post a comment.