QCP_CONFIG(5)

NAME
qcp_config - Configuration options for qcp

DESCRIPTION
qcp(1) obtains run-time configuration from the following sources, in order:

        1. Command-line options

        2. The user's configuration file (usually ~/.qcp.conf) on either side of the connection (see NEGOTIATION)

        3. The system-wide configuration file (usually /etc/qcp.conf) on either side of the connection

        4. Hard-wired defaults
Each option may appear in multiple places, but only the first match is used. Note: Configuration file locations are platform-dependent. To see what applies on the current platform, run qcp --config-files.

FILE FORMAT
qcp uses the same basic format as OpenSSH configuration files. Each line contains a keyword (the option name) and one or more arguments. Option names are single words. They are case insensitive; hyphens and underscores are ignored. In other words, you can use UPPERCASE, lowercase, CamelCase, mIxEDcAse, SHOUTY_SNAKE_CASE, kebab-case, Train-Case, whatever you like. Arguments are separated from keywords, and each other, by whitespace. (It is also possible to write Key=Value or Key = Value.) Arguments may be surrounded by double quotes ("); this allows you to set an argument containing spaces. If a backslash, double or single quote forms part of an argument it must be backslash-escaped i.e. \" or \\ Comments are supported; # introduces a comment (up to the end of the line). Empty lines are ignored. qcp supports Host and Include directives in way that is intended to be compatible with OpenSSH. This allows you to tune your configuration for a range of network hosts.

EXAMPLE
 Host old-faithful
 # This is an old server with a very limited CPU which we do not want to overstress.
 # old-faithful isn't its DNS name; it's a hostname aliased in ssh_config.
 rx 125k # 1 Mbit limit. Yes, it's a really old server.
 tx 0 # tx 0 means
 # This server runs a tight firewall; inbound UDP is only allowed on certain ports.
 RemotePort 65400-65500

 Host *.internal.corp 172.31.200.*
 # This is a nearby data centre which we have a dedicated 1Gbit connection to.
 # We don't need to use qcp, but it's convenient to use one tool in our scripts.
 # We specify the group both by domain name and netblock: the qcp client process
 # matches against whatever you give on the command line, and the qcp server
 # uses only the connecting IP address.
 # (IPv6 addresses would work here too.)
 rx 125M
 tx 0
 rtt 10

 # For all other hosts, try to maximise our 400Mbit fibre
 Host *
 rx 50M # we have 400Mbit download
 tx 12.5M # we have 100Mbit upload; we could also have written this out in full, or as
 rtt 150 # most servers we care about are an ocean away
 congestion bbr # this works well for us

CONFIGURATION DIRECTIVES

Host pattern [pattern ...]
    Introduces a host block. All following options - up to the next Host - only apply to hosts matching any of the patterns given. Pattern matching uses '*' and '?' as wildcards in the usual way. A single asterisk '*' matches all hosts; this is used to provide defaults. A pattern beginning with '!' is a negative match; it matches all remote hosts except those matching the rest of the pattern. Pattern matching is applied directly to the remote host given on the QCP command line, before DNS or alias resolution. It does _not_ resolve hostname to IP address. However, if you connect to hosts by IP address, patterns (for example 10.11.12.*) do work in the obvious way. The remote (server) process reads its own configuration file and matches using the IP address passed to it by the ssh server in the SSH_CONNECTION or SSH_CLIENT environment variables.

Include file [file ...]
    Include the specified file(s) in the configuration at the current point. Glob wildcards ('*' and '?') are supported in filenames. User configuration files may refer to pathnames relative to '~' (the user's home directory). Filenames with relative paths are assumed to be in ~/.ssh/ if read from a user configuration file, or /etc/ssh/ if read from a system configuration file. An Include directive inside a Host block retains the Host context. This may be useful to apply common directives to multiple hosts with minimal repetition. Note that if an included file begins a new Host block, that will continue to apply on return to the including file. It is possible for included files to themselves include additional files; there is a brake that prevents infinite recursion.

CONFIGURABLE OPTIONS
The following options from the CLI are supported in configuration files: rx, tx, rtt, congestion, initial_congestion_window, port, timeout, udp_buffer, packet_threshold, time_threshold, initial_mtu, min_mtu, max_mtu, address_family, ssh, remote_qcp_binary, ssh_options, remote_port, remote_user, time_format, ssh_config, ssh_subsystem, color, tls_auth_type, aes256, io_buffer_size Refer to qcp(1) for details. In configuration files, option keywords are case insensitive and ignore hyphens and underscores. (On the command line, options must be specified in kebab-case.) For example, these declarations are all equivalent:
    RemotePort 12345
    remoteport 12345
    remote_port 12345
    Remote_Port 12345
    ReMoTePoRt 12345
    rEmOtE-pOrT 12345

CONFIGURATION DEBUG TOOLS
The --dry-run mode reports the negotiated network configuration that we would have used for a given proposed transfer.

    2025-02-10 09:32:07Z INFO Negotiated network configuration: rx 37.5MB (300Mbit), tx 12.5MB (100Mbit), rtt 300ms, congestion algorithm Cubic with initial window <default>
As configurations can get quite complex, it may be useful to understand where a particular value came from. qcp will do this for you, with the --show-config option. Specify a source and destination as if you were copying a file to/from a host to see the configuration that would apply. For example:

     $ qcp --show-config server234:some-file /tmp/
     +-------------------------+-------------+-------------------------------+
     | field | value | source |
     +-------------------------+-------------+-------------------------------+
     | (Remote host) | server234 | |
     | AddressFamily | any | default |
     | Congestion | Cubic | default |
     | InitialCongestionWindow | 0 | default |
     | Port | 10000-12000 | /home/xyz/.qcp.conf (line 26) |
     | RemotePort | 0 | default |
     | Rtt | 300 | default |
     | Rx | 37M5 | /home/xyz/.qcp.conf (line 22) |
     | Ssh | ssh | default |
     | SshConfig | [] | default |
     | SshOptions | [] | default |
     | TimeFormat | UTC | /etc/qcp.conf (line 14) |
     | Timeout | 5 | default |
     | Tx | 12M5 | /home/xyz/.qcp.conf (line 23) |
     +-------------------------+-------------+-------------------------------+
Add `--remote-config` to the command line to have the server report its settings. These come in two blocks, the static configuration and the final configuration after applying system defaults and client preferences.

     % qcp --remote-config server234:some-file /tmp/
     2025-02-10 09:26:02Z INFO Server: Static configuration:
     +---------------+-------------+-------------------------------+
     | field | value | source |
     +---------------+-------------+-------------------------------+
     | (Remote host) | 10.22.55.77 | |
     | Port | 10000-12000 | /home/xyz/.qcp.conf (line 26) |
     | Rtt | 1 | /home/xyz/.qcp.conf (line 19) |
     | Rx | 125M | /home/xyz/.qcp.conf (line 17) |
     | TimeFormat | UTC | /home/xyz/.qcp.conf (line 25) |
     | Tx | 125M | /home/xyz/.qcp.conf (line 18) |
     +---------------+-------------+-------------------------------+
     2025-02-10 09:26:02Z INFO Server: Final configuration:
     +-------------------------+-------------+-------------------------------+
     | field | value | source |
     +-------------------------+-------------+-------------------------------+
     | (Remote host) | 10.22.55.77 | |
     | AddressFamily | any | default |
     | Congestion | Cubic | default |
     | InitialCongestionWindow | 0 | default |
     | Port | 10000-12000 | /home/xyz/.qcp.conf (line 26) |
     | RemotePort | 0 | default |
     | Rtt | 1 | /home/xyz/.qcp.conf (line 19) |
     | Rx | 123M | config resolution logic |
     | Ssh | ssh | default |
     | SshConfig | [] | default |
     | SshOptions | [] | default |
     | TimeFormat | UTC | /home/xyz/.qcp.conf (line 25) |
     | Timeout | 5 | default |
     | Tx | 125M | /home/xyz/.qcp.conf (line 18) |
     +-------------------------+-------------+-------------------------------+

TIPS AND TRAPS
1. Like OpenSSH, for each setting we use the value from the first Host block we find that matches the remote hostname. 2. Each setting is evaluated independently. In the example above, the Host old-faithful block sets rx but does not set rtt. Any operations to old-faithful inherit rtt 150 from the Host * block. 3. The tx setting has a default value of 0, which means “use the active rx value”. If you set tx in a Host * block, you probably want to set it explicitly everywhere you set rx. 4. The qcp client process does NOT resolve hostname to IP address when determining which `Host` block(s) to match.
   This is consistent with OpenSSH.

       * However, the qcp server process ONLY matches against the IP address passed to it by the OpenSSH server.
       * Therefore, in an environment which may act as both qcp client and server, you may need to specify options by both hostname and netblock.

BUILDING A CONFIGURATION
We suggest the following approach to setting up a configuration file.
   1. Set up a `Host *` block specifying `Tx` and `Rx` suitable for your local network uplink.

    * In a data centre environment, the bandwidth limits will likely be whatever your network interface is capable of. (If the data centre has limited bandwidth, or your contract specifies something lower, use that instead.) * In a host connected to a standard ISP connection, the bandwidth limits will be whatever you're paying your ISP for. If you're not sure, you might use speedtest.net or a similar service.
2. Make a best-guess to what the Round Trip Time might be in the default case, and add this to `Host *`.

    * If you mostly deal with servers on the same continent as you, this might be somewhere around 50 or 100ms. * If you mostly deal with servers on the other side of the planet, this might be 300s or even more.
3. Add any other global options to the `Host *` block

    * If this machine will act as a qcp server and has a firewall that limits incoming UDP traffic, set up a firewall exception on a range of ports and configure that as `port`. * Set up any non-standard `ssh`, `ssh_options` or `ssh_config` that may be needed. * If you want to use UTC when printing messages, set `TimeFormat`.
4. If there are any specific hosts or network blocks that merit different network settings, add `Host` block(s) for them as required.

    * Order these from most-specific to least-specific. Be sure to place them above `Host *` in the config file.
5. Try it out! Copy some files around and see what network performance is like. Note that these files need to be large (hundreds of MB or more) to really see the effect, and you need to go into gigabytes to see it do well on a good fibre connection. You might like to use `--dry-run` mode to preview the final network configuration for a proposed file transfer. If the output isn't what you expected, use `--show-config` and `--remote-config` to see where the various settings came from. Note that `tx' and `rx' are the opposite way round, from from the server's point of view!

FILES

~/.qcp.conf
    The user configuration file (on most platforms)

/etc/qcp.conf
    The system configuration file (on most platforms)

~/.ssh/ssh_config
    The user ssh configuration file

/etc/ssh/ssh_config
    The system ssh configuration file

SEE ALSO
qcp(1), ssh_config(5) https://docs.rs/qcp/latest/qcp/doc/performance/index.html

AUTHOR
Ross Younger