Jetstream Primer¶

Overview¶

The Jetstream server runs as a single process, with an optional relay process, when required:

jetstream-server

The main service that sends and receives files.

jetstream-relay

An optional service that can reroute transfers when setting up DMZ or when more advanced firewall/network traversal is required.

Default Configuration¶

Jetstream services use the following ports:

jetstream-server: TCP 8886, UDP 8886

jetstream-relay: TCP 8887, UDP 8886 (public – opened on behalf of jetstream-server)

License server: outgoing TCP 5053, 5055 (Required by Jetstream server for demo licenses or when using Cumul8 hosted license server)

TCP port 8886 is used for API communication with the Jetstream server. UDP port 8886 is used for sending and receiving data. In case where the relay service is used, TCP port 8887 is used for internal communication with the Jetstream server, and the Jetstream relay will open UDP ports for sending and receiving on behalf of the connected Jetstream server (default UDP 8886). If these ports need to be adjusted, you can edit the corresponding Jetstream configuration file. (See Editing Configuration, jetstream server --api-port, jetstream server --recv-port, jetstream relay_server --control-port.)

Additionally, the jetstream-server service needs to allocate one outgoing UDP port for each destination. By default these ports are allocated dynamically, but if desired, can be specified when creating destinations. If you are restricting outgoing traffic through the firewall, you will either need to open up the outgoing ephemeral range (dynamic port allocation) of the specific ports you specified when the destinations were created.

To receive transfers, you will need to open the Jetstream receive port (default UDP 8886) in your firewall. In order the accept connections from the Jetstream client, you will additionally need to open the Jetstream API port (default TCP 8886). If you’re using a demo license or Cumul8 hosted license server, you will also need to open TCP port 5053 and 5055 to allow connection to the licensing server.

After installation, Jetstream services are disabled. In order to use Jetstream, you will need to start the service manually and optionally enable it to start automatically on boot. A single service is capable of both sending and receiving files.

Jetstream services will run as root (Linux, macOS) or Local System Account (Windows), and require users to authenticate before they can transfer files.

Jetstream listens for API connections on all network interfaces. To change this behaviour, see --api-allow-remote-control, --api-host.

By default, Jetstream is configured to use a persistent state directory located in /var/lib/jetstream/state on Linux and macOS, and C:\WINDOWS\system32\config\systemprofile\AppData\Local\Cumul8\Jetstream\state on Windows. See --persistent-state-dir.

The default trigger directory is /var/lib/jetstream/triggers on Linux and macOS, and C:\WINDOWS\system32\config\systemprofile\AppData\Local\Cumul8\Jetstream\triggers on Windows. See --trigger-dir.

Jetstream server collects anonymized telemetry data, such as round trip times, transfer rates, or file size statistics, and sends them to Cumul8 as per the EULA. To learn what data is collected please refer to Telemetry. You can use --disable-telemetry to disable this behaviour.

Where Do Transfers Go?¶

The path to which transferred files are written is determined by three variables:

The receiving server’s sandbox path or system root;

A per-transfer destination path; and,

Each file’s target path.

The path of a file written by the Jetstream receiver is then: /<receiver_sandbox_path>/<transfer_path>/<file_target_path>.

By default, a Jetstream server is not sandboxed, and defaults to writing transfers directly below the system’s root folder. To force all incoming transfers to be stored within a specific directory, include the --sandbox-dir command line parameter when starting the server.

The per-transfer destination path is specified when creating a transfer with createTransfer().

Finally, each file’s target path is specified as part of the fileMappings option with createManifest().

Destination path mapping summary¶
Sandbox Directory	Destination Path	File Target Path	Full Path
<None>	<None>	`/mnt/data/file.txt`	`/mnt/data/file.txt`
<None>	<None>	`file.txt`	`/file.txt`
`/storage`	<None>	`/mnt/data/file.txt`	`/storage/mnt/data/file.txt`
`/storage`	`/repository1`	`/mnt/data/file.txt`	`/storage/repository1/mnt/data/file.txt`
`/storage/%u`	<None>	`/mnt/data/file.txt`	`/storage/<username>/mnt/data/file.txt`
`/storage/%u`	`/repository1`	`/mnt/data/file.txt`	`/storage/<username>/repository/mnt/data/file.txt`

Example:

In this example, no server sandbox has been specified, so the transfer alone will specify the path created on the receiving server.

Here, the jscp command is used to initiate a transfer. No transfer destination path is specified.

jscp /source/my_file jetstream02.lan:/target/my_file

The file at the receiving server will be written to /target/my_file, dictated entirely by the file’s target path..

Example:

In this example, the receiving server was started with --sandbox-dir set to /storage, and thus sandboxes all transfers below this folder.

Again, the jscp command is used to initiate a transfer. No transfer destination path is specified.

jscp /source/my_file jetstream02.lan:/target/my_file

The file at the receiving server will be written to /storage/target/my_file, combining the server’s sandbox and the file’s target path..

Example:

Again, the receiving server was with started its sandbox specified as /storage.

The jscp command is used to initiate a transfer. This time, the path /project is specified as the destination path for all files in the transfer.

jscp -d /project /source/my_file jetstream02.lan:/target/my_file

The file at the receiving server will be written to /storage/project/target/my_file, combining the server’s sandbox, the transfer’s destination path, and the file’s target path.

Example:

This example replicates the transfer above, but uses the command line API instead of the jscp command.

$ jetstream api createDestination --destinationAddress=jetstream02.lan --sendRateMax=1500000
$ jetstream api createManifest --fileMappings /source/my_file:/target/my_file
$ jetstream api createTransfer --destinationId <destinationId> --manifestId <manifestId> --destinationPath /project

If the receiving server has been sandboxed below /storage then the file will be written to /storage/project/target/my_file, combining the server’s sandbox, the transfer’s destination path, and the file’s target path.

If the receiving server has not been sandboxed, then the file will be written to /project/target/my_file, combining the transfer’s destination path, and the file’s target path.

User Management¶

Jetstream integrates with your system’s built-in authentication. This allows any users with login permissions on the server to send to and retrieve files from the Jetstream server. For more information see User Management.