Relay Configuration¶

A relay lets two JetStream servers transfer files when neither one can accept a connection from the other.

There are two reasons to use one:

Security. You do not want to put a computer on the internet if that computer can also read your confidential assets.
NAT and firewalls. A receiver behind a NAT or a company firewall has no address that a sender can connect to.

Note

The relay changed in version 3.0.0. The earlier relay was a proxy in front of one server, and a transfer could use one relay for the sender and a different relay for the receiver. The new relay is a meeting point: both servers connect out to the same relay, and the relay joins the two connections. If you have a configuration for the earlier relay, read Changes from earlier versions.

How it works¶

A sender usually connects to a receiver. This is only possible if the receiver has an address that the sender can reach. A receiver behind a NAT does not have one.

With a relay, both servers connect out:

The receiver connects to the relay and keeps the connection open.
A sender connects to the relay and asks for that receiver.
The relay tells the receiver to make a new connection.
The relay joins the two connections together.

Each connection was made by a JetStream server, so no server has to accept a connection from the internet. Only the relay does.

The relay does not read the data. The two servers encrypt the transfer between themselves, and the relay does not have the keys of either server. The relay copies the encrypted data and knows only how many bytes it copied.

A Demilitarized Zone (DMZ) is a computer that has access to the internet but not to the private network. A firewall between the DMZ and the private network refuses all connections into the private network. The relay runs in the DMZ. This works because the JetStream server starts the connection to the relay, and the firewall permits that direction.

Requirements¶

The relay service is installed with the server service, but it does not start automatically. Start it with the standard OS system service commands.

The relay opens one TCP port, 8887 by default. All three types of connection arrive on this port: the registration from a receiver, the connection from a sender, and the new connection that the receiver makes when the relay asks for one.

The relay needs a static IP address, and the firewall must permit connections to this port. The two JetStream servers do not need a static address or a firewall rule for incoming connections.

A relayed transfer uses TCP. The receiver must have --recv-tcp-port set. If you give a relay address but no TCP port, the server starts and writes a warning in the log. Relayed transfers to that receiver then fail.

Which receivers can use the relay¶

A receiver must be in the relay’s list of permitted receivers. Make a text file with one receiver public key on each line:

# Receivers permitted to use this relay
AAEEAMboYh1KVN2t...
AAEEAFl0ENgqNRly...

To find the public key of a receiver, read the server log at start-up:

Public key: AAEEAMboYh1KVN2t...

The getServerInfo result also gives this key.

The file contains only public keys. It is not secret, and you can keep it with your other configuration files.

The relay reads the file again when the file changes:

To permit a new receiver, add its key. You do not have to restart the relay.
To remove a receiver, delete its line. The relay closes that receiver’s connection in a few seconds.

The receiver proves its identity with the same key that the transfer uses. There is no new password or certificate to install.

Configuration¶

Relay¶

Start the relay with its port and the list of permitted receivers:

[relay]# jetstream relay_server --control-port=8887 \
             --allowed-receivers=/etc/jetstream/relay-allow.txt
The jetstream relay_server --control-port value is used for the jetstream server --recv-relay-port of the receiver, and for the relayPort of the destination.

At the first start-up the relay makes its own key file. You do not have to make it.

Receiver¶

Start the receiver with the address and port of the relay:

[receiver]# jetstream server --recv-relay-host=relay --recv-relay-port=8887 \
                --recv-port=8886 --recv-tcp-port=8886
The jetstream server --recv-relay-host value must be the hostname or IP address of the relay.

The jetstream server --recv-relay-port value must be the same as the jetstream relay_server --control-port of the relay.

The jetstream server --recv-tcp-port option is necessary. A relayed transfer uses TCP.

The public key of this receiver must be in the --allowed-receivers file of the relay.

To find if the receiver can be reached, read the relayRegistered field of the getServerInfo result:

true — senders can reach this receiver through the relay.
false — they cannot. The receiver tries again in the background. Look in the receiver log and in the relay log for the reason. The most usual reason is that the public key of the receiver is not in the --allowed-receivers file.

Sender¶

Start the sender without special configuration:

[sender]# jetstream server

Destination¶

Give the address of the relay, and the public key of the receiver:

>>> createDestination(destinationAddress='receiver', destinationPort=8886,
...                   relayAddress='relay', relayPort=8887,
...                   authenticateDestination=True,
...                   destinationPublicKey='AAEEAMboYh1KVN2t...')
The relayAddress and relayPort must be the address and jetstream relay_server --control-port of the relay.

The destinationPublicKey is necessary for a relayed destination. The relay finds the receiver by a name that is calculated from this key, so the sender cannot find the receiver without it. Use the same key that the receiver gives in getServerInfo.

The destinationAddress and destinationPort are the address and jetstream server --recv-port of the receiver. The transfer does not connect to this address, but the destination keeps it as its name.

To use one relay for all destinations, give jetstream server --send-default-relay-host and jetstream server --send-default-relay-port to the sender. A createDestination call can then use a different relay, or no relay.

Reverse dial: no relay computer at all¶

If the sender has an address the receiver can reach, you do not need a relay computer. The receiver can register with the sender directly, and the sender asks it to connect whenever it has data to send. This is called reverse dial. Every connection is made by the receiver, so the receiver needs no reachable address — the usual case is a receiver behind a NAT pulling files from a server on the internet.

Receiver¶

Configure the receiver exactly as for a relay, but give the sender’s address and API port:

[receiver]# jetstream server --recv-relay-host=sender --recv-relay-port=8886 \
                --recv-port=8886 --recv-tcp-port=8886

The receiver does not know, and does not need to know, whether it registered with a relay or with a sender. The relayRegistered field of its getServerInfo result means the same thing in both cases.

You can also register a running receiver with addRegistration(). You do not have to restart it.

Sender¶

Permit the receiver to register, and create the destination with the public key of the receiver:

>>> authorizeReverseReceiver('AAEEAMboYh1KVN2t...')
>>> createDestination(destinationAddress='receiver', destinationPort=8886,
...                   authenticateDestination=True,
...                   destinationPublicKey='AAEEAMboYh1KVN2t...')
A receiver can register with a sender in two cases: its public key is in the list of authorized reverse receivers, or a destination on the sender has its public key and a reverseDial that is not "never". authorizeReverseReceiver() adds a key to the list. revokeReverseReceiver() removes it. The receiver then disconnects within a few seconds, unless a destination also permits it.

reverseDial is "auto" by default. The sender uses reverse dial if the receiver is registered when the connection starts. If not, it connects to the address. Use "always" to require reverse dial, and "never" to prevent it.

If you do not use the list, make the destination permanent. If the destination is garbage collected, the receiver loses its registration until the destination is created again.

The destinationPublicKey is necessary, for the same reason as with a relay: the sender finds the receiver by a name calculated from this key.

The destination result has a receiverRegistered field: true means the receiver is connected and transfers can start; false means it is not — look in the receiver log for the reason.

A reverse-dial transfer uses QUIC if the receiver can connect back over QUIC. If it cannot, the transfer uses TCP. A destination cannot use a relay and reverse dial at the same time.

Limitations¶

A relayed transfer uses TCP. The QUIC transport cannot use a relay. If a transfer asks for the udp transport, the server uses TCP and writes the reason in the log.
A relayed transfer does not have a speed guarantee. The relay does not control the speed of each transfer, and it does not divide its capacity between them. The speed depends on the relay, on its network, and on how many transfers use it.
A relayed destination must have a public key. See Destination.

Changes from earlier versions¶

If you have a configuration for the relay of an earlier version, make these changes:

Use one relay, not two. Both servers now connect to the same relay. A separate relay for the sender and for the receiver is not necessary, and the two-relay configuration no longer applies.
Give ``–allowed-receivers`` to the relay. Without it, or without --insecure-allow-any-receiver, the relay does not start.
Give ``–recv-tcp-port`` to the receiver. Without it, relayed transfers to the receiver fail. The receiver starts and writes a warning in its log.
Change the destination. Set destinationAddress to the receiver, not to the relay, and give relayAddress, relayPort and destinationPublicKey.
Remove ``–recv-relay-multiplex``. The option is removed. The server does not know it and stops with an error at startup.