3. rist URL Syntax and Examples

This documents the URL options for ristsender and ristreceiver by which you can individually customize each RIST connection independently of the global parameters set in the command lines. Note that the binaries support up to ten -o URLs, separated by commas. Note that all the options below apply to the rist:// URL with the exception of "mifice"e, which applies to inbound multicast packets for ristsender or outbound on rist receiver.

This help text consists of three parts. The default help text you may see with the --helurl command line option, descriptive text for each of the options below it, and then finally, additional examples.

URL Help output

Main help can be accessed via ristsender --helpurl

Usage: append to end of individual rist:// url(s) as ?param1=value1¶m2=value2...

Simple, Main and Advanced Profiles param buffer=### buffer size in milliseconds param bandwidth=### max bandwidth in Kbps param return-bandwidth=### max bandwidth for messaging return in Kbps param reorder-buffer=### reordering buffer size in ms param cname=abcde arbitrary name for stream for display in logging param rtt-min=### minimum expected rtt param rtt-max=### maximum expected rtt param verbose-level=# Disable -1; Error 3, Warning 4, Notice 5, Info 6, Debug 7, simulation/dry-run 100 param miface=(device) device name (e.g. eth0) for multicast param session-timeout=### timeout in ms for closing of connection where keep-alive fails

Main and Advanced Profiles param aes-type=# 128 = AES-128, 256 = AES-256 must have passphrase too param secret=abcde encryption passphrase param virt-dst-port destination port inside the GRE header param keepalive-interval=### interval in ms param key-rotation=## number of IP packets before a key rotation is triggered param congestion-control=# mitigation mode: (0=disabled, 1=normal, 2=aggressive) param min-retries=## min retries count before congestion control kicks in param max-retries=## max retries count param weight=# default weight for multi-path load balancing. Use 0 for duplicate paths. param stream-id=# ID number (even number) for multiplex/demultiplexing steam in peer connector

Advanced Profile param compression=1|0 enable lz4 levels

Usage: append to end of individual udp:// url(s) as ?param1=value1&param2=value2...

Additional Explanations

Below are additional explanations of each of the above parameters:

• buffer=### sets the buffer size in milliseconds. The buffer size will work best at four to seven times the ping time. 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. We often say that there should be a “tuning period” for a RIST configuration. The log will tell you how many packets were recovered during any connection. We recommend taking a day or two when setting up a connection that you expect to run for long periods of time, monitoring the log, and adjusting the buffer up (or down) little by little, where necessary.

• bandwidth=### sets the maximum bandwidth in Kbps. It is necessary to configure the bandwidth to be higher than the max bandwidth of your stream(s). This is in order to allow room for messaging headroom, plus the re-requested packets. When tuning a connection for the first time, analyze your stream statistics locally at first, then start at 10% higher for a constant bitrate, 100% higher for variable bitrate. Especially for VBR, provide generous "headroom" in your bandwidth. You can always reduce it when configuring and tuning the connection.

• return-bandwidth=### sets the maximum bandwidth in Kbps for just the receiver-to-sender direction. This is an option which may sometimes help avoid congestion insofar as it may limit re-request messages in poor network conditions.

• reorder-buffer=### sets the size for a secondary buffer in which after all re=requested packets have been received, the out-of-order packets are released in the correct order. in most cases there should be no need to adjust this setting, but it may be helpful in conjuction with very long distance/large buffer/poor network conditions.

• cname=abcde provides a canonical name for the media. If multi-plexing more than one stream through a tunnel, this provides a convenient way to identify a particular stream within the log. You should make it standard practice to assign a cononical name whenever multi-plexing. (see also stream-id, below).

• rtt-min=### sets the minimum rtt setting in milliseconds. This can help reduce congestion by reducing the number of repeated re-requests in poor network conditions. More importantly, for very long-distance or connections that traverse under-sea cables, it may be important to adjust this setting. if you search for "Global ping Statistics" you will find a number of sites which test and track such times between various city pairs; this data is sometimes helpful for intercontinental connection tuning.

• rtt-max=### sets the maximum rtt setting in milliseconds. See rtt-min for a more complete description. in most cases, minimum and maximum should be set to be equal to one another.

• verbose-level=# 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.

• aes-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.

• miface=(device) sets the adapter for multicast protocol, as in the example &miface=eth1. Note that the rist:// URLs must be unicast IP addresses; however, the media stream URLs, as in udp://xxx.xxx.xxx.xxx may be multicast.

• session-timeout=### terminates the RIST connection after inactivity/lack of keepalive response for the limit (in milliseconds) which you set with this parameter.

• secret=abcde 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 the "secret" specify the "aes-type" parameter. The rotating keys shall be placed inside the rtcp messages, using your passphrase as the pre-shared key. Be sure that the passphrase for sender and receiver match!

• virt-dst-port The port within the GRE tunnel. This has nothing to do with the media port(s). If the GRE is device /dev/tun11, having an address of 1.1.1.2, and the virtual destination port is 10000, and your media is using port 8193/4, the operating system will use 1.1.1.2:10000 as the destination from the sender's point of view, or the inbound on the receiver's point of view. libRIST will make use of that device/IP/port. As far as your media source and media player are concerned, the media is on ports 8193/4 on their respective interfaces. The media knows nothing of the tunnel.

• keepalive-interval=### time in milliseconds between pings. As is standard practice for GRE tunnels, the keep alive helps ensure the tunnel remains connected and open should no media be traversing it at a given time.

• key-rotation=## sets the key rotation period in milliseconds when aes and a passphrases are specified.

• congestion-control=# libRIST provides built in congestion control, which is important in situations in which a sender drops off the connection, but the receiver still sends re-requests. The three options for this parameter are 0=disabled, 1=normal and 2=aggressive. In general, don't set the parameter to "aggressive" unless you've definitely established that congestion is a problem.

• min-retries=## sets a minimum number of re-requests for a lost packet. Note that setting this too high can lead to congestion. Regardless of this setting, the size of the buffer and the roundtrip time will render too high a minimum value here irrelevant.

• max-retries=## sets a maximum number of re-requests for a lost packet. See "min-retries."

• weight=# sets the relative share for load balanced connections. The best way to describe this will be to provide an example. The default is five, so in a setup where two paths are given weights of 5 and 10 respectively, the former would receive 1/3 of packets sent, and the latter would receive 2/3.

• stream-id=# sets the encapsulated udp destination port, this must be even. This parameter can be applied to the rist:// url on the sender, and to the udp:// or rtp:// URL on the receiver. The former "assigns" the ID. The latter allows you to specify which multiplexed stream the receiving side will output as a given IP/port output URL. You can therefore have up to ten streams in and ten streams out for a single RIST connection. Each individual stream must have a unique ID and its output shall then handle the ID accordingly. It is possible to send multiple streams through a GRE tunnel and only output selected streams at the receiving side, though that wastes the bandwidth. Such a routing scenario, however, allows for a sending side to send all streams to multiple receivers via one command line, putting the "onus" on the receivers to sort out their desired streams.

• compression=1|0 utilizes liblz4 to compress all traffic in the GRE tunnel.

Examples