Skip to content

Channel Configuration

Jump to bottom
Michael Barker edited this page Feb 26, 2020 · 91 revisions

Channels are specified via an Aeron URI provided when adding a publication or subscription. The Aeron URI has the following format:

aeron-uri = ["aeron-spy:"] "aeron:" media [ "?" param *( "|" param ) ]
media     = *( "[^?:]" )
param     = key "=" value
key       = *( "[^=]" )
value     = *( "[^|]" )

To help with building a channel URI string then use ChannelUriStringBuilder for Java or ChannelUriStringBuilder for C++, URIs can also be parsed with ChannelUri for Java and ChannelUri for C++.

All Media Transports

The following parameters are available on all media transports when applied to a Publication:

  • alias - (optional) Reserved param which can contain a user provided string to identify a channel to for an application.

  • term-length - (optional) The term length to be applied to the log when adding a Publication. This parameter overrides the aeron.term.buffer.length or aeron.ipc.term.buffer.length system properties.

  • sparse - (optional) Boolean value to indicate if a sparse file should be used to back the log buffers. This parameter overrides the aeron.term.buffer.sparse.file system property.

  • session-id - (optional) 32-bit signed integer value that is assigned for the session id to override the default generation for publications, or to restrict the scope of a subscription to a single session. Session ids additionally support tags to pickup a configuration from another entity. For example, a session specific subscription could tag reference a specific tagged publication.

The following 3 parameters can be applied as a group to set an initial position on an Exclusive Publication for replay purposes:

  • init-term-id - (optional) The initial term id which can be applied to an Exclusive Publication.
  • term-id - (optional) The current term id which can be applied to an Exclusive Publication.
  • term-offset - (optional) The current term id which can be applied to an Exclusive Publication.

Subscriptions can be tethered for if they participate in local flow control.

  • tether - (optional) Boolean value to indicate if a subscription should be a permanent tether for local flow control.

IPC Media - Inter Process Communication

If shared memory is to be used for communications on the same machine between threads or processes then the IPC media value can be applied. This is the highest throughput and lowest latency means of communicating between two process or threads on the same machine.

aeron:ipc

UDP Media

The Aeron URI uses a media value of udp to determine that messages will be sent via the UDP protocol. To distinguish between Unicast and Multicast, the UdpChannel will look at the specific parameters supplied and infer the appropriate choice.

Many of the values options are network addresses, in this case they can take for the form of a host name, IPv4, or IPv6 address enclosed in square brackets.

Configuration Properties

Both Unicast and Multicast channel configuration uses the same set of properties. Distinguishing between unicast and multicast is done by examining the endpoint address of the channel. The important configuration options are:

  • endpoint - (required unless MDC) The socket address to which publications will send messages and from which subscriptions will receive messages. This takes the <host>:<port> format, where both the host and port are required.

  • interface - (optional) The socket address that identifies that local interface that will be used for receiving messages (and sending messages in the multicast case). The value can take the form <host>[:<port>][/<subnet mask>]. When specified the system will scan the local interfaces for one that matches the specified pattern. The default value for this field is 0.0.0.0:0\0 (or [::]:0/0 for IPv6). With a unicast configuration this will simply map to any local address and will listen for messages from all local network interfaces. This setting will only impact the behaviour of subscriptions for multicast, unicast publications will effectively ignore this value. With a multicast configuration this will scan all of the local network interfaces and will use the first non-loopback network interface that supports multicast, falling back to the local loopback if none are found.

  • control - (optional) Multi-Destination-Cast (MDC) control address to be used for dynamically allocating new destination streams. The value will be an IP address and port, e.g. 192.168.0.1:40456. When set for the publication with MDC then control-mode should also be set.

  • control-mode - (optional) Valid value is manual if using the Publication.addDestination(String) / Publication.removeDestination(String) API, or dynamic, if initiated by connections to the control address.

  • ttl - (optional) The TTL used for multicast traffic. Only used when the endpoint specified is a multicast address. This value is passed directly as the IP_MULTICAST_TTL and should be within the range 0 - 255. A value outside this range will generate an exception set as the socket option.

  • mtu - (optional) The MTU is the Maximum Transmission Unit which sets the length limit for a UDP datagram payload on this stream. This overrides the aeron.mtu.length property for the driver when adding a new Publication.

  • reliable - (optional) The reliable property when applied to a Subscription disables the NAK'ing of lost packets on the stream. The lost packets are gap filled so the stream can progress. Valid values are true and false with the default being true.

  • linger - (optional) Timeout in nanoseconds a network publication should linger around to service NAKs. This parameter overrides the aeron.publication.linger.timeout system property.

  • tags - (optional) Identity and references for associating channels in simplifying configuration. See tags for more details.

  • eos - (optional) Indicates if a publication should send an End Of Stream (EOS) flag in its heartbeat messages when closed. Valid values are true and false with the default being true.

  • group - (optional) Indicates if a subscription should behave as part of a receiver group such as with multicast. This will impact NAK behaviour and related semantics. It will default to true for multicast and false for unicast. For a subscriber to MDC unicast stream it will default to false but should be changed to true if the group is larger than 2.

  • rejoin - (optional) Indicates if an image should rejoin a stream if it gets disconnected due to timeout or falling behind. Defaults to true.

  • cc - (optional) Indicates what congestion control algorithm should be applied. Default to static which is static window for just flow control. Can be set to cubic for the Cubic congestion control algorithm. Cubic is recommend over a WAN or congested networks.

  • fc - (optional) Indicates what flat control algorithm should be used and the configuration for it. See Flow Control Configuration

Examples

Simple Unicast, with any local address used for binding subscriptions:

aeron:udp?endpoint=192.168.0.1:40456

Unicast with a specific address to receive messages:

aeron:udp?endpoint=192.168.0.1:40456|interface=192.168.0.3

Unicast with a search pattern to identify an address to receive messages. This is especially useful if you have a large number of machines on the same network and want to reuse the same configuration string across all of them.

aeron:udp?endpoint=192.168.0.1:40456|interface=192.168.0.0/24

Use host names instead of addresses:

aeron:udp?endpoint=localhost:40456

Or use IPv6:

aeron:udp?endpoint=[::1]:1234|interface=[::1]

Simple multicast:

aeron:udp?endpoint=224.0.1.1:40456

It is also possible to specify an IPv6 address, but the IPv6 address portion needs to placed inside square brackets []:

aeron:udp?endpoint=[ff02::1]:40456

To specify which interface to use, add the interface parameter. It will find the interface with that matches whose bound address matches the one specified. For an interface config, such as the following:

en0: flags=8863<UP,BROADCAST,SMART,RUNNING,SIMPLEX,MULTICAST> mtu 1500
    ether 04:0c:ce:e3:c8:c0 
    inet6 fe80::60c:ceff:fee3:c8c0%en0 prefixlen 64 scopeid 0x4 
    inet 192.168.1.4 netmask 0xffffff00 broadcast 192.168.1.255
    nd6 options=1<PERFORMNUD>
    media: autoselect
    status: active

Then the following configuration will ensure that the 'en0' interface is used.

aeron:udp?endpoint=224.0.1.1:40456|interface=192.168.1.4

Or similarly for IPv6.

aeron:udp?endpoint=[ff02::1]:40456|interface=[fe80::60c:ceff:fee3:c8c0]

However, having to specify a full IP for the interface can be difficult. Especially if you want to share the configuration throughout a number of machines in the same network. Therefore with the interface specification you specify a subnet mask to allow Aeron to search for an appropriate interface. The following will find an interface on the 192.168.1.x network. If there are multiple interfaces that match the criteria, the result will be undefined. The first interface returned from NetworkInterface.getNetworkInterfaces() that matches the IP address pattern and supports multicast will be used.

aeron:udp?endpoint=224.0.1.1:40456|interface=192.168.1.0/24

Specifically the /24 means that the first 24 bits of the IP address will be used when comparing against the IP addresses on the interface. Similarly for IPv6.

aeron:udp?endpoint=[ff02::1]:40456|interface=[fe80::60c:ceff:fee3]/88

Hostnames can be used instead of IP addresses for both the group and interface parameters.

aeron:udp?endpoint=all-systems.mcast.net:40456|interface=localhost

Simple multicast with specified TTL of 16.

aeron:udp?endpoint=224.0.1.1:40456|ttl=16

Multi-Destination-Cast dynamic publication using control port of 40456.

aeron:udp?control=localhost:40456

Multi-Destination-Cast dynamic subscription using local endpoint port of 40457 and control port at 192.168.0.1 and port 40456

aeron:udp?endpoint=localhost:40457|control=192.168.0.1:40456|control-mode=dynamic

Multi-Destination-Cast manual publication using control port of 40456.

aeron:udp?control=localhost:40456|control-mode=manual

Outgoing Channel Spy

If you wish to subscribe to a local Publication without receiving the packets back in the network interface, for which they are being sent out, then this is possible by spying on a network publication as an optimisation. A spy Subscription will receive the messages over IPC without a copy.

aeron-spy:aeron:udp?endpoint=224.20.30.39:54326

aeron-spy:aeron:udp?endpoint=224.0.1.1:40456|interface=192.168.1.0/24|session-id=tag:7

Note:

  • Spy subscriptions are not applicable to IPC media.
  • Spy subscriptions do not affect the Publication connected status by default. They can simulate a connected publication if the aeron.spies.simulate.connection property is set, in which case the publication can progress if it only has spies.
  • Spy subscriptions apply back-pressure like normal Subscriptions.

Flow Control Configuration

Clone this wiki locally