Throttle bandwidth with “cstream”.

cstream is a general-purpose stream-handling tool (like UNIX dd) usually used in command-line-constructed pipes.

Direct data streams, with bandwidth limiting, FIFO, audio, duplication and extended reporting support.

Relevant Features:

  • Exact throughput limiting, on the incoming side. Timing variance in previous reads are counterbalanced in the following reads.
  • Precise throughput reporting. Either at the end of the transmission or everytime SIGUSR1 is received. Quite useful to ask lengthy operations how much data has been transferred yet.
  • SIGHUP causes a clean shutdown before EOF on input, timing information is displayed.
  • Build-in support to write its PID to a file, for painless sending of these signals.
  • Build-in support for FIFOs. Example usage is a ‘pseudo-device’, something that sinks or delivers data at an appropriate rate, but looks like a file, i.e. if you test soundcard software. See the manpage for examples.
  • Built-in data creation and sink, no more redirection of /dev/null and /dev/zero. These special devices speed varies greatly among operating systems, redirecting from it isn’t appropriate benchmarking and a waste of resources anyway.
  • Accepts ‘k’, ‘m’ and ‘g’ character after number for “kilo, mega, giga” bytes for overall data size limit.

Short usage instructions:

-V     = print version number to stdout and exit with 0
-v <n> = verbose [default: off]
         0 = nothing
         1 = report bytes transferred and throughput
         2 = also throughput after first read/write
         3 = also seperate throughput for read and write (unimplemented)
         3 = verbose stats on every read/write
-b <n> = blocksize [default: 8192]
-B <n> = buffer (at most) <n> bytes [default: one block]
-c <n> = Concurrency, writing done by a seperate process
         0 = no concurrency, one one process
         1 = read side buffers
         2 = write side buffers
         3 = both sides buffer, -B amount of data will be transferred at once
-n <n> = overall size of data [default: unlimited]
-t <n> = throughput in bytes/sec [default: unlimited]
         if positive, bandwith is average over whole session.
         if negative, every write is delayed to not excceed.
-i <s> = name of input file, - = generate stream yourself
         to use stdin, use -i ''
-o <s> = name of output file, - = just sink data
         to use stdout, -o ''
-I <s> = Type of input file
-O <s> = Type of ouput file
         'f' = fifo (create it)
         'a' = set audio modes on file (i.e. CD quality)
         'N' = don't use TCP even if filename has ':'
         't' = tee - in addition to outfile, copy stream to fd 3
         'D' = O_DIRECT
         'S' = O_SYNC
         [Multiple chars allowed]
-p <s> = Write pid as ascii integer to file <s>
-l       include line count in statistics
-w <n> = Set write block size (-c 5 only)
-S       Don't output statistic on SIGINFO
-T <n> = Report throughput every <n> seconds
SIGINFO causes statistics to be written to stderr
SIGUSR1 causes statistics to be written to stderr
SIGUSR2 causes loop end after next buffer transfer
<file>  if -i has not been used, specifies input file
-6 <n>  Use IPV6: -1 = don't, 1 = allow both, 2 = force v6
        On some platforms server mode 1 forces ipv6, as
        they don't open both v4 and v6 ports from one bind call.

Data Transfer Examples:

Compress a folder (bzip) and transfer it over the network at a specified speed:

tar -cj /opt/backup\
 | cstream -t 5m\
 | ssh root@destination_host\
 "tar -xj -C /opt/backup"

Same as previous, but writing the archive file named with current date to destination host:

tar -cj /opt/backup\
 | cstream -t 5m\
 | ssh root@destination_host\
 "cat > /opt/backups/`date +%Y%m%d`.bz2"

Comments are closed.