FileBarge usage

FileBarge transfers one or more regular files directly over TCP. One machine runs a receiver and the other runs a sender. The sender connects to the receiver, which chooses whether and where each offered file is stored.

Help output

filebarge -h, filebarge -help, and filebarge --help print the following complete command-line reference:

Usage:

  filebarge receive [options] <output>
  filebarge send [options] <address> <input> [<input> ...]


Commands:

  receive, r  Receive files from one sender.
  send, s     Send one or more files to a receiver.


Protocol options:

  --chksum f32|none   Select one checksum or disable checksumming.
  --checksums <list>
                      Comma separated list of checksum algorithms.
                      Sender: List offered checksum algorithms.
                      Receiver: Accept checksums in preferred order.

  --comp sq|none      Select one compression or disable compression.
  --compressions <list>
                      Comma separated list of compression algorithms.
                      Sender: List offered compression algorithms.
                      Receiver: Accept compressions in preferred order.

  --crypt asc|none    Select one crypto suite or disable encryption.
  --crypto-suites <list>
                      Comma separated list of crypto suites.
                      Sender: List offered crypto suites.
                      Receiver: Accept crypto suites in preferred order.

  --connect-timeout <seconds>
                      Set connection timeout; default: 4 seconds.

  --message <message>
                      Set the hello message.

  --secret <value>    Enable encryption with this secret.
  --secret-file <path>
                      Read the encryption secret from a file.

  --no-perms          Do not transfer POSIX permissions.
                      Sender: Do not send permissions.
                      Receiver: Ignore sent permissions.

  --timeout <seconds>
                      Set activity timeout; default: 8 seconds.


Tool options:

  --forgiving         Continue after recoverable file errors.
  --no-progress       Do not print transfer progress.
  --quiet             Suppress normal standard-output messages.


Receive options:

  --1                 Accept exactly one sender-named file.
  --address <address>
                      Bind to an IPv4 or IPv6 address only.

  --listen            Accept another sender after this session.
  --match
                      Require the transmitted name to match <output>.

  --newer             Replace only with a strictly newer file.
  --overwrite         Permit replacement of existing files.
  --port <port>       Bind to this port; 0 selects an OS port.


Send options:

  --recursive         Traverse directory inputs recursively.


Other options:

  -h, -help, --help   Print this usage information.
  --version           Print the version number.
  --                  End options.

Supported list values:

  --checksums         fletcher32
  --compressions      squinch
  --crypto-suites     ascon

Use 'filebarge receive --help' or 'filebarge send --help' for details.

--newer implies --overwrite, but replaces a destination only when the incoming modification time is strictly newer. --no-perms prevents FileBarge from applying transmitted POSIX permission bits. --address <address> binds only to one IPv4 or IPv6 address; without it, FileBarge listens on all available addresses.

Sending files

<address> may be an IPv4 address, IPv6 address, or DNS name. Append a port as example.net:9576 or [2001:db8::1]:9576; do not use brackets around an IPv6 address without a port. Sender connections always select their port in the address, and port 0 is invalid.

filebarge send receiver.example.net report.pdf
filebarge send 192.0.2.12:9576 one.txt two.txt
filebarge send --recursive [2001:db8::12]:8421 assets/

An input may be a regular file or directory. Directories send their immediate files by default, without including the directory name in the transmitted name. --recursive sends all files below an input directory and preserves their paths relative to that directory. Dotfiles are included. Empty directories are ignored, and symbolic links are followed as ordinary files.

FileBarge discovers files incrementally. It connects only after finding a first file; if no file is found, it reports that nothing needs doing and succeeds without opening a connection.

Connection and session options

--port <port> selects the receiver's bind port. The default is 8421; port 0 requests an operating-system-selected port.

--connect-timeout <seconds> sets a whole-second timeout for DNS resolution and connection setup. Its default is four seconds.

--timeout <seconds> sets the advertised activity timeout. It accepts 0 for the default eight seconds, or 0.1 through 25.0 in tenths of a second. Each peer applies the timeout advertised by the other peer and uses keep-alive packets while waiting.

--listen keeps a receiver active after each finished or failed session. It still serves only one sender at a time.

--message <message> sets the optional UTF-8 peer-identification message included in the protocol hello packet. It is limited to 255 bytes.

--quiet suppresses normal status output. --no-progress keeps status messages but hides the progress indicator. Files from 128 kB to below 10 MB show progress in 20% steps, and larger files use 10% steps. --forgiving continues after errors that the protocol classifies as recoverable; malformed protocol data and connection failures are always fatal.

Integrity, compression, and encryption

--checksums <list> and --compressions <list> select comma-separated algorithms. Currently fletcher32 and squinch are available. On a sender, these options choose what it may offer; on a receiver, they choose what it accepts and, in list order, prefers. --chksum f32|none and --comp sq|none are convenient single-algorithm forms.

--crypto-suites <list> selects comma-separated encryption suites. Currently ascon is available. On a sender, it chooses what the sender may offer; on a receiver, it chooses what the receiver accepts and, in list order, prefers. --crypt asc|none is the convenient single-suite form. none disables the corresponding feature.

Use the same --secret <value> or --secret-file <path> on both sides to enable encrypted transfers. A secret beginning with 0x is interpreted as even-length hexadecimal bytes; another value is used as text bytes. --secret-file reads the first line and avoids placing a secret in shell history. The protocol's encryption construction is specified in Protocol.

Destination safety

Transmitted paths always use /. FileBarge rejects absolute paths, .., empty components, and . components. On Windows it also rejects \ in a path component before converting / to the native separator.

File contents are written to a temporary file first. The destination is changed only after the transfer ends cleanly and any requested checksum succeeds. Replacing an existing file may retain its inode and ownership where possible, so the final copy into that existing file is not always atomic.