Command Line Interface

Synopsis

jetstream [options] subcommand [subcommand-options]

Description

jetstream is the main way to interact with the JetStream server. There are three sub commands:

Options

--version

Print version information

jetstream server

Options

Warning

Before you install this version, remove the --disable-port-multiplex and --recv-relay-multiplex lines from the response file. Both options are removed. The server does not know them and stops with an error at startup.

--api-host arg

TCP client API host address. If specified, bind API to listen on this address (overrides --api-allow-remote-control).

--api-port arg (=8886)

TCP client API control port.

--api-allow-remote-control

Allow API connections from remote machines (can be overriden by api-host).

--api-min-ssl-version arg (=TLS1.2)

Minimum allowed SSL protocol (TLS1.3,TLS1.2,TLS1.1,TLS1.0).

--api-ssl-cert arg

Path to a file containing the SSL certificate to use for API connections. --api-ssl-cert-key must also be specified.

--api-ssl-cert-key arg

Path to a file containing the SSL private key to use for API connections. --api-ssl-cert must also be specified.

--api-connect arg

Actively create an API connection to the specified client.

--api-disable-shared-tokens

Disable the creation and use of tokens for anonymous downloads.

See also

Shared Links

--api-disable-api-tokens

Disable the creation and use of tokens for logon access.

See also

API Tokens

--web-share-port arg

Serve shared files to web browsers on this TCP port.

Specify a port to enable the feature. There is no default and no separate enable option. If you do not specify a port, the server does not start the web share tier.

By default the tier listens on the loopback address only. Then you must run a reverse proxy on the same machine, which terminates TLS and forwards requests to this port. To let the tier terminate TLS itself, give --web-share-tls-cert and --web-share-tls-key. To listen on an address that is not a loopback address, also give --web-share-bind.

You cannot use this option together with --api-disable-shared-tokens. The server stops with an error, because the web share tier can only serve shares that use download tokens.

--web-share-url arg

The public HTTPS address that recipients open to download shared files in a browser, for example https://share.example.com.

The address must include the https scheme and must not include a path. The server sends this address to clients, which add it to the share message. If you do not specify an address, the share message does not include a web link.

Do not use --external-address for this purpose. That address must continue to identify the JetStream server, or client links stop working.

--web-share-warn-size arg (=10737418240)

The size in bytes above which JetStream tells recipients and sharers that a browser download takes a long time and that the JetStream application is faster. The note applies to shares that download as an archive, that is, shares of more than one file.

This is a message only. JetStream does not block a download of any size.

--web-share-bind arg (=127.0.0.1)

The address that the web share tier listens on. Without a certificate, the default address needs a reverse proxy on the same machine. For an address that is not a loopback address, you must also give --web-share-tls-cert and --web-share-tls-key. If you do not, the server does not start.

--web-share-tls-cert arg

The PEM certificate chain that the web share tier uses to terminate TLS itself, without a reverse proxy. The server loads the file again when it changes. A download in progress keeps the certificate that it started with.

--web-share-tls-key arg

The PEM private key for --web-share-tls-cert. Give the two options together.

--web-share-trusted-proxy arg

An address that can set the X-Forwarded-For header on the web share tier. The loopback address is always trusted. From other addresses, the tier ignores the header and uses the address of the connection. You can give more than one address. If an address is not valid, the server does not start.

--web-share-branding arg

The path to the branding file (JSON) for the browser download pages. The file sets colors, the product name, the logo path and link addresses. It changes only the values that it names. If the server cannot read the file, or a value in it is not valid, the server does not start. To load the file again on a running server, use server.setWebShareBranding.

Warning

Before you install an older version of the server, remove all --web-share-* lines from the response file. An older server does not know these options and stops with an error at startup.

--max-cloud-cache-size arg (=4294967296)

Maximum size, in bytes, of cloud file cache.

See also

S3

--max-cloud-cache-download-size arg (=52428800)

Maximum size, in bytes, of cloud file cache to use per download transfer.

See also

S3

--max-cloud-cache-upload-size arg (=4242538496)

Maximum size, in bytes, of cloud file cache to use per upload transfer.

See also

S3

--max-cloud-connections arg (=16)

Maximum number of simultaneous connections to cloud storage.

--max-cloud-retry arg (=6)

Maximum number of retries for one cloud storage request.

--cloud-cache-file arg

A file to use for caching cloud requests. Must exist and be at least --max-cloud-cache-size bytes big.

See also

S3

--disable-cloud-etag-verify

Do not confirm cloud storage writes against the ETag the store returns.

By default the server sends a Content-MD5 header with each upload and compares the ETag in the reply with the digest it calculated. The store rejects a corrupted upload, and a mismatch fails the file. Use this option only if an S3-compatible store does not return a standard ETag. Verification costs one MD5 pass over each uploaded part.

See also

S3

--default-file-driver arg

Backend file driver for reading and writing. One of mem_map, or raw.

--default-file-driver-read arg (=mem_map)

Backend file driver for reading. One of mem_map, or raw. When you also give --default-file-driver, this option applies to reads.

--default-file-driver-write arg (=raw)

Backend file driver for writing. One of mem_map, or raw. When you also give --default-file-driver, this option applies to writes.

--sandbox-dir arg

Sandbox jetstream into path. %u token can be used for user name.

See also

Sandboxing

--trigger-dir arg

Folder containing trigger scripts.

--trigger-on-api

Call trigger scripts for all API commands.

--trigger-log

Print additional debugging information about triggers and trigger output. On macOS and Linux the output goes to standard out, not to the --log file.

--persistent-state-dir arg

Folder to store persistent server state.

Note

Persistent state directory can’t be shared between servers. Each running server will need its own independent persistent state directory.

--persistent-destinations arg

Load and save destinations (if --persistent-state-dir is present).

--persistent-transfers arg

Load and save transfers (if --persistent-state-dir is present). --persistent-destinations is required.

--encryption-state-dir arg

Folder for the server’s identity key file (encryption_state.json), when it is not in --persistent-state-dir. The identity key is how peers know this server, so it must stay after a restart.

--durable-state-dir arg

Folder for the receiver’s resume checkpoints, when they are not in --persistent-state-dir. With a checkpoint, an interrupted transfer continues from where it stopped and does not start again from the beginning.

--send-host arg

This option has no effect on connections. The sender does not bind a local address or port. The operating system chooses them for each connection. If the server cannot resolve the address, it does not start.

--recv-host arg

UDP receiver host address. If specified, bind server to listen on this address.

--recv-port arg (=8886)

UDP receiver port(s).

--max-file-write-threads arg (=4)

Maximum number of simultaneous file write threads.

Note

For the best performance, the number of file write threads should match the number of receiver ports specified.

--max-file-write-cache-size arg (=4294967296)

Maximum size, in bytes, of data to buffer when writing files. The limit applies to the whole server.

--recv-auth-required arg (=1)

Auth is required to receive transfers (always true when the server is running as root).

--send-default-relay-host arg

The address of the relay to use for every new destination. A createDestination call can give a different relayAddress, or no relay. See Relay Configuration.

--send-default-relay-port arg (=8887)

The port of the default relay. It must be the same as the --control-port of the relay.

--recv-tcp-port arg

The TCP port for transfers. Give one port for each --recv-port, in the same order. If you do not give this option, the server accepts TCP transfers only on the API port, and only while --recv-tcp-shared-port is on, which is the default.

This option is necessary for a relay. See Relay Configuration.

--tcp-session-streams arg (=32)

The maximum number of data streams in one TCP transfer session. The control stream is additional. Applies to --recv-tcp-port and to --recv-tcp-shared-port.

--recv-tcp-shared-port arg (=1)

Accept TCP transfers on the API port, and not on a separate port. This is on by default. To turn it off, use --recv-tcp-shared-port=false. Independent of --recv-tcp-port: you can give one option, both, or neither.

--recv-relay-host arg

The address of the relay to register with. If you give this option, the Receiver connects out to the relay and holds the connection open, so that senders can reach the Receiver through the relay. Use this option when the Receiver is behind a NAT or a firewall and senders cannot connect to it.

For a relay, you must also give --recv-tcp-port. A relayed transfer uses the TCP data plane. If you give a relay but no TCP port, the server starts and writes a warning to the log, and transfers through the relay do not work.

For a sender (give the address and API port of the sender), you do not need --recv-tcp-port. The Receiver answers over QUIC on the port it already listens on. The server refuses to start only if the Receiver can answer no dial request at all, that is, if it has no data plane.

The public key of this Receiver must be in the --allowed-receivers file of the relay. For a sender, the sender must authorize this Receiver with send.authorizeReverseReceiver, or have a destination that uses this Receiver’s public key. If it does not, the registration is refused.

You can also do this with the API and no command-line option: use recv.addRegistration. The Receiver holds one connection for each address you give, and opens them again when it restarts. Any user can do this; you do not need administrator rights, because this makes a path and does not give permissions. The Go:JetStream client application does it for you when you log in to a server, so that the server can send files to your computer through your NAT.

To find if the Receiver is registered, read the relayRegistered field in the getServerInfo result. The Receiver tries again in the background, so a relay address in the configuration does not show that the Receiver can be reached.

--recv-relay-port arg (=8887)

The port of the relay. It must be the same as the --control-port of the relay.

--recv-allow-discovery arg (=1)

This option has no effect. The server does not answer discovery requests.

--recv-stale-part-file-seconds arg (=604800)

Delete the part files of an interrupted transfer after nothing has written to them for this many seconds. The default is seven days. Set it to 0 to keep part files until the sender cancels the transfer.

The receiver writes each incoming file to a .jetpart_<transfer id> directory next to its destination, and renames it into place when the transfer completes. If the transfer stops and the sender never comes back, those files stay on disk. This option removes them. The receiver checks at startup and at every garbage collection, which is once an hour by default.

The receiver never deletes the files of a transfer it still holds, for example a suspended transfer. When it deletes a transfer’s part files, it also deletes the transfer’s resume checkpoint. If the sender resumes that transfer later, the transfer starts again from the beginning.

The list of part files is kept in --persistent-state-dir, or in --durable-state-dir when there is no persistent state directory. With neither, the list is kept in memory and a restart loses it.

--name arg

Specify a name for this server.

This can then be retrieved using the getServerInfo() API call.

--external-address arg

Specify FQDN or IP address and port that will be used to create shared links (host:API-port)

See also

Shared Links

--license-location arg

Specify license server address (host:port).

--license-password arg

Specify license password.

See also

License Configuration

--superuser arg

Specify a user name that will be recognized as a superuser (multi-use).

See also

Superusers

--supergroup arg

Specify a group name whose members will be recognized as superusers (multi-use).

See also

Superusers

--incoming-rate-limit arg

Cap on the incoming bandwidth in kilobits per second.

--outgoing-rate-limit arg

Cap on the outgoing bandwidth in kilobits per second.

--borrow-incoming-rate

Increase the outgoing rate limit by unused incoming rate.

--borrow-outgoing-rate

Increase the incoming rate limit by unused outgoing rate.

--max-concurrent-transfers arg (=10)

The largest number of transfers that the server runs at the same time, at all urgency levels. Other transfers wait in the queue. Set it to 0 to remove the limit. A value that a superuser changes at runtime is saved, and replaces this value at the next start.

--max-transfers-per-destination arg (=1)

The largest number of transfers to one destination that run at the same time. A destination is one machine, one user and one session. A second transfer to a destination at the limit reports waiting and keeps its place in the queue. Transfers to other destinations start normally. Set it to 0 to remove the limit. A value that a superuser changes at runtime is saved, and replaces this value at the next start.

The largest number of browser downloads from web shares that run at the same time. This limit is separate from --max-concurrent-transfers, so the two counts add. Downloads above the limit continue at a very low rate until a place is free. Set it to 0 to remove the limit.

The largest number of browser downloads to one recipient that run at the same time. A recipient is one browser for one share, not one IP address. The default 0 sets no limit.

--unreachable-transfer-timeout arg (=1800)

How long a transfer may wait with no connection to its destination before the server suspends it, in seconds. The default is 1800, which is thirty minutes. Use 0 to switch the deadline off, so that a transfer waits for its destination indefinitely.

The transfer is suspended, not cancelled. Every byte already delivered is kept. The server continues to try the destination, and when it can be reached the transfer starts again by itself, from the point where it stopped. No operator action is necessary.

A suspended transfer of this kind reports suspendedUnreachable in the API. Use that field to tell it from a transfer that a person suspended: a transfer a person suspended stays suspended until a person resumes it.

This setting is a backstop. When a transfer sets its own timeoutSeconds, that value applies first and this setting changes nothing. The deadline applies only while the server cannot reach the destination. A transfer that waits its turn in the queue does not come near it.

--bbr-loss-threshold-pct arg (=5)

UDP transfers only. When one round trip loses more than this percentage of its bytes, the sender reduces the data it keeps in flight to what got through. Set it to 0 to turn this off.

--bbr-loss-backoff-pct arg (=70)

UDP transfers only. The largest part, in percent, of the round’s data in flight that the sender keeps after a loss cut.

--bbr-delay-threshold-ms arg (=0)

UDP transfers only. When the one-way delay in a round trip stays more than this many milliseconds above its recent low, or more than twice the lowest round-trip time, the sender reduces the data it keeps in flight. The default 0 turns this off.

--bbr-delay-backoff-pct arg (=50)

UDP transfers only. When --bbr-delay-threshold-ms applies, the sender removes this percentage of the data in flight above one bandwidth-delay product.

--scavenger-target-pct arg (=50)

While a more urgent transfer runs on this server, a connection that carries only less urgent transfers gives way to it. The connection gives way when its one-way delay is more than a target above its low. The target is this percentage of the path’s one-way delay. Set this option and --scavenger-target-floor-ms to 0 to turn this off.

--scavenger-target-floor-ms arg (=2)

The smallest target, in milliseconds, for --scavenger-target-pct.

--log arg

Output all log data into the given file instead of standard out.

See also

Logging

--log-file-creates

Add a log entry for every received file.

--log-transfer-dir arg

Folder for the log files of single transfers. A transfer that sets transferLog writes its own log file in this folder. The server creates the folder if it does not exist, and does not start if it cannot.

--log-level arg (=3)

Change the verbosity of the log file.

Available log levels are:

  • 0: Fatal errors only

  • 1: Errors

  • 2: Warnings

  • 3: Informational messages

  • 4: Security audit events

  • 5: Debug errors

  • 6: Debug information

--disable-telemetry

Disable collection of telemetry data.

--response-file arg

Response file that contains additional command-line arguments (alternately use ‘@file’).

--check-args

Report arguments this build does not recognize, then exit without starting anything.

The server writes one UNKNOWN_TOKEN= line per unrecognized token to standard error, then UNKNOWN_COUNT= and KNOWN_COUNT=. It exits 0 whether or not it finds a problem. A non-zero exit means the check itself could not run.

Use this option when the service will not start and the log is empty. The server reads its arguments before it opens the log file, so an argument it does not know stops it with nothing written:

jetstream server @/etc/jetstream-server.rsp --check-args

This can happen after an upgrade. An option that a later version removed stays in the response file, and the new server stops on it every time it starts.

This option checks names, not values. --recv-port=abc is a name the server knows with a value it cannot use. It passes this check and still stops the server.

--print-known-args

With --check-args, and turning it on by itself, also write the arguments the server does recognize to standard output, one per line. A value that needs quotes gets them back.

Send that output to a new file to get a copy of the response file with the unrecognized arguments removed. The server never edits the file itself:

jetstream server @/etc/jetstream-server.rsp --check-args --print-known-args > /tmp/clean.rsp

CAUTION: Read the removed arguments on standard error before you replace anything. An argument is removed because this build does not know it, which can mean a typographical error as easily as a removed option.

Three kinds of argument cannot be written back, so the server refuses the whole request, exits non-zero and prints nothing: an argument that contains a quote character, one that contains a line break, and an empty one. None of the three survives a re-read, because the response file has no escape character. Correct the argument by hand. Nothing was changed.

jetstream relay_server

See also

Relay Configuration

Options

--control-port arg (=8887)

The TCP port of the relay. Receivers register on this port, senders connect on this port, and the reverse connections from a receiver arrive on this port. The relay needs only this one inbound port.

--allowed-receivers arg

The path to the file that lists the receivers which can register with this relay. Put one receiver public key on each line. Lines that start with # are comments.

A receiver writes its public key to its log at start-up (Public key: ...) and also gives it in the getServerInfo result.

The file contains only public keys. It is not secret.

The relay reads the file again when the file changes. You do not have to restart the relay to add a receiver. If you remove a receiver, the relay closes that receiver’s connection in a few seconds.

You must give this option, or --insecure-allow-any-receiver. If you give neither, the relay does not start.

--identity-file arg

The path to the file where the relay keeps its own key. The relay makes this file at the first start-up. The default location is jetstream-relay-identity.json, in the same directory as --allowed-receivers.

The relay needs a key because the connection from a receiver uses TLS in both directions.

--insecure-allow-any-receiver

Do not use this option on a computer that other networks can reach.

The relay accepts a registration from any receiver, and does not use TLS. Any computer can then register, and a sender can be connected to it. Use this option only for tests on an isolated computer.

You cannot use this option together with --allowed-receivers.

--log arg

Output all log data into the given file instead of standard out.

--response-file arg

Response file that contains additional command-line arguments (alternately use ‘@file’).

jetstream api

See also

jetstream-api:index

Options

--host arg (=localhost)

Address of JetStream server to control

--api-control-port arg (=8886)

Default API port

--user arg

User name for API authentication (cannot be used at the same time as token)

--authToken arg

Token for API authentication (cannot be used at the same time as user)

--authTokenSession arg

Token session for sharing transfers between instances of token authentication

--superuser

Run the API command as a superuser

--wrangler

Run the API command as a wrangler. See Wranglers.

--no-auth

Skip API authentication. If used, the --user, --authToken, --authTokenSession and --superuser options are ignored