|
|
|
The ristsender is provided as a fully featured example program. You may use it as-is for testing or even production, or you may examine the code for ideas in creating your own utilities. This documents ristsender by printing its help text, then providing explanations for it, and by providing examples of its usage.
|
|
|
|
|
|
|
|
The help text consists of two parts. The default help, which documents the global parameters which affect all RIST connections run from a particular instance, plus specific URL help, which sets the parameters for each RIST connectiong between sender and receiver pair separately.
|
|
|
|
|
|
|
|
**Main Help - Global Parameters**
|
|
|
|
|
|
|
|
Main help can be accessed via ristsender --help >enter<
|
|
|
|
|
|
|
|
Usage: %s [OPTIONS]
|
|
|
|
Where OPTIONS are:
|
|
|
|
-i | --inputurl udp://... * | Comma separated list of input udp URLs |
|
|
|
|
-o | --outputurl rist://... * | Comma separated list of output rist URLs |
|
|
|
|
-b | --buffer value | Default buffer size for packet retransmissions |
|
|
|
|
-s | --secret PWD | Default pre-shared encryption secret |
|
|
|
|
-e | --encryption-type TYPE | Default Encryption type (0, 128 = AES-128, 256 = AES-256)|
|
|
|
|
-p | --profile number | Rist profile (0 = simple, 1 = main, 2 = advanced) |
|
|
|
|
-t | --tun IfName | TUN interface name for oob data input |
|
|
|
|
-S | --statsinterval value (ms) | Interval at which stats get printed, 0 to disable |
|
|
|
|
-v | --verbose-level value | To disable logging: -1, log levels match syslog levels |
|
|
|
|
-h | --help | Show this help |
|
|
|
|
-u | --help-url | Show all the possible url options |
|
|
|
|
* == mandatory value
|
|
|
|
Default values: %s
|
|
|
|
--profile 1
|
|
|
|
--stats 1000
|
|
|
|
--verbose-level 6
|
|
|
|
ristsender version 3.1.0.2
|
|
|
|
|
|
|
|
**Additional Explanations**
|
|
|
|
|
|
|
|
Below are additional explanations of each of the above parameters:
|
|
|
|
|
|
|
|
* -i --inputurl refers to the incoming stream(s), which is subsequently to be sent to the RIST receiver. This is normally a udp or rtp media stream from a host/port in the private network or the localhost adapter. As an example, udp://@127.0.0.1:8193 would listen, which we specify as a listener via the "@" sign to port 8193 of the localhost adapter. A URL such as udp://192.168.1.10:8195 would be interpreted as reaching out to the host at 192.168.1.10 for the media stream. You will find additional information on the inputurl parameter in the section dedicated to the URL parameters. You can list up to ten URLs, separating them by commas.
|
|
|
|
|
|
|
|
* -o | --outputurl refers to the rist receiver destination(s). rist://123.124.125.126:8194 would refer to an external host ristreceiver at that address and port. Note the even numbered port. The outputurl parameter provides a large number of individual customization possibilities. We refer you to the section dedicated to the URL parameters, below. You can list up to ten URLs, separating them by commas.
|
|
|
|
|
|
|
|
* -b | --buffer refers to the size of the buffer which stores the most recently sent packets. If the ristreceiver sends a request to retransmit a specific packet, if it is in the buffer, the ristsender resends it. The buffer size will work best at four to seven times the ping time between the longest locations. This allows time for requests for the retransmission of a lost or corrupted packet, and the subsequent retransmission of its replacement. If your stream traverses undersea fiber routes or other types of sometimes unstable or congested routes, you may require an even bigger buffer. This buffer will "delay" the stream by the amount of the buffer, but the stream will arrive without added jitter.
|
|
|
|
|
|
|
|
* -s | --secret PWD sets the specified passphrase for Main or Advanced profile encryption. Note that simple protocol does not support encryption, and that you must in addition to -s specify the -e (encryption type) parameter. The rotating keys shall be placed inside the rtcp messages, using your -e parameter as the pre-shared key.
|
|
|
|
|
|
|
|
* -e | --encryption-type specifies the specific encrytion. Specify "128" for AES-128 or "256" for AES-256. Remember that you must also specify the pass phrase, and that encryption is not supported for the simple protocol at all.
|
|
|
|
|
|
|
|
* -p | --profile number specifies the profile type for the RIST connection. Choose "0" for simple, "1" for main, or "2" for advanced
|
|
|
|
|
|
|
|
The simple profile provides a minimal implemenation for transport of an rtp or udp stream over a given port between two hosts, with an additional port used for status and re-request messages. Note that it is expected that simple profile viewer applications such as vlc 4.x, currently in beta, will promote widespread adoption of the RIST protocol to a global audience.
|
|
|
|
|
|
|
|
The main profile provides additional features, most notably the optional use of a tunnel (utilizing only one port) between hosts through which both messages and media can traverse, with support for encryption and multiplexing. It also provides for multiple network paths, which enables load balancing and redundancy.
|
|
|
|
|
|
|
|
The advanced profile adds lz4 compression of the GRE tunnel, a quick but efficient form of compression.
|
|
|
|
|
|
|
|
In general, you should find that the Simple and Main profile configured libRIST connections should be interoperable with other vendors' RIST implementations, depending upon how true each vendor implementation is to the RIST standards, which are still relatively new. The Advanced profile is compatible only with connections using the libRIST implementation.
|
|
|
|
|
|
|
|
* -t | --tun IfName The device name for the Main or Advanced protocol tunnel which shall convey both media stream and messaging. This would typically be a device name such as tun0. ristsender will create the actual tunnel as a true bi-directional tunnel similar to an SSL tunnel. You, however, will create an adaptor in the OS before running ristsender. For example, at a bash prompt as root, you might run ip tuntap add mode tun dev tun21
|
|
|
|
|
|
|
|
* -S | --statsinterval value (ms) specifies the time in milliseconds (default is 1000 ms or 1 second) between statistics summaries. A value of zero disables the stats. When testing or tuning libRIST, you will find the stats, and in particular, the statistics pertaining to the resends and lost packets an important means of understanding how best to set up your connections.
|
|
|
|
|
|
|
|
* -v | --verbose-level value The verbosity settings match the standard Syslog options. These are self explanatory: -1 for disable. 3 for errors only. 4 adds warnings. 5 adds notices. 6 adds info. 7 for debug mode. 100 allows you to dry-run or simulate the RIST connection.
|
|
|
|
|
|
|
|
* -h | --help displays the help text shown above, which is for the global settings of one or more RIST connections controlled by this instance.
|
|
|
|
|
|
|
|
* -u | --help-url displays the help regarding URL construction, which provides the settings on a connection by connection basis.
|
|
|
|
|
|
|
|
**Examples**
|
|
|
|
|
|
|
|
| Code| Meaning|
|
|
|
|
| ------ | ------ |
|
|
|
|
| ristsender -p 0 -i rtp://@192.168.1.3:8200 -o rist://@123.124.125.126:20000| Using simple protocol, listen on local IP 192.168.1.3, port 8200 for an incoming rtp stream, then send it via rist to external host 123.124.125.126:20000. In this case, 20001 will be used for messaging, so you'll wish to make sure the firewall on 123.124.125.126 is open on both ports. Simple protocol and limited options should be the starting point for your testings.
|
|
|
|
| ristsender -p 1 -e 128 -s blarg -i udp://192.168.1.5:11111 -o rist://123.124.125.126:8200| Using main protocol with AES128 encryption and a pre-shared key of "blarg," get udp stream from 192.168.1.5, port 11111, , then send it via encrypted rist to external host 123.124.125.126:8200. In this case, since no tunnel is specified, 8201 will be used for messaging, so you'll wish to make sure the firewall on 123.124.125.126 is open on both ports.|
|
|
|
|
| ristsender -p 1 -t tun11 -i udp://192.168.1.5:11111 -o rist://@99.98.97.96:8200| Listen on a tunnel set up on the ristsender's external/public address (99.98.97.96. Since the sender is listening, it's easier for a receiver that may be behind a gateway to reach out and establish the connection. ristsender will set up the tunnel, so only one port will be necessary. Note that for clarity's sake, this example shows an unencrypted connection, but we expect that most providers using rist with a tunnel will be applying encryption.|
|
|
|
|
| ristsender -i 'udp://225.0.0.4:1971?miface=eth1&virt-dst-port=1968' -o 'rist://@162.247.59.66:8022?cname=listening&bandwidth=10000&buffer-min=1000&buffer-max=1000&rtt-min=50&rtt-max=500&reorder-buffer=25&virt-dst-port=1968amp;weight=0&congestion-control=2' -p 1 -e 1 -s blarg -v 8| This command line takes as input a multicast stream (225.0.0.4:1971) at device eth1. Note that the information for composing an input URL for multicast is better described on the next page, which is about URLs. The output URL indicates that the sender will listen on its port 8022 (the sender's IP address is 162.247.59.66). There are a number of connection specific parameters regarding buffer size and others which will be explained in the helpurl topic. The -p here indicates this is the main protocol, and the -e and -s parameters specify AES-128 encryption and passphrase.|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
\ No newline at end of file |
