English · 日本語
Put hosts and profiles in ~/.config/netcap/ (or $NETCAP_CONFIG_DIR, or $XDG_CONFIG_HOME/netcap).
One entry per line; everything after # is a comment. Templates are in examples/.
# name OS route
laptop mac -
server mac server
gamepc win gamepc
| Column | Value |
|---|---|
| name | The name you pass to netcap status <name>: letters, digits, _, ., and -, starting with a letter or digit. all is reserved |
| OS | One of mac (pf + dummynet), linux (tc), win (NetQosPolicy) |
| route | Your usual ssh destination: a Host from ~/.ssh/config, or user@host. - for the machine running netcap itself. netcap install writes this line |
# name device=value …
game laptop=2/2 server=1/1 gamepc=off
quiet laptop=1/1 server=1/1
none laptop=off server=off gamepc=off
A value is up/down in Mbit/s, on (the device's own default, as netcap on <name> without flags), or off. Decimals work (0.5/2). 0 is an error: netcap refuses it and changes nothing (dummynet on macOS reads 0 as unlimited, so it cannot mean "cut off"). On macOS a value can go up to 2147.483647 (dummynet holds the rate as bit/s in a 32-bit integer); the device refuses more. To lift a cap, use off. Devices not listed are left untouched (quiet leaves gamepc as it is). A profile name follows the same rule as a device name.
netcap profile set game laptop=2/2 gamepc=off writes this line for you: it adds game, or replaces its line where it is (a comment after it stays), with the devices in the order of hosts. It refuses, and changes nothing, what netcap use would refuse: a device not in hosts or a value it cannot read. netcap profile rm game removes the line. Both only edit the file; no device is asked. With --json, set prints {"profile": "game", "devices": {...}, "created": true | false} and rm {"profile": "game", "devices": {...}} (what it had).
netcap use <profile> --for 30m takes the same times as netcap on --for (1m to 24h): each device the profile caps (up/down or on) gets on … --for, and lifts the cap by itself at the deadline, even if the controller is gone. A device set to off is lifted at once. An agent older than 0.11.0 refuses --for and changes nothing; that device shows as failed.
netcap export prints this machine's hosts and profiles as JSON; netcap import reads them back.
Use it for a backup, or to set up another controller (operations.md).
netcap export > netcap.json
netcap import netcap.json # on the same or another machine; - reads stdin
netcap import netcap.json --replace # overwrite existing hosts and profiles (keeps hosts.bak and profiles.bak)- Nothing secret is exported. No keys (
~/.ssh/netcapstays where it is) and no ssh settings: a route stays a Host name, resolved by the importing machine's own~/.ssh/config. Caps and defaults are not exported either; they live on the devices - This machine (route
-) is not taken over elsewhere. Imported on another machine, it would point at that machine, so it is skipped (and removed from profiles) with a message. Add it back withnetcap install <name> --ssh <dest> - An export is checked before anything is written: names, OS, routes, and profile values; the exporting machine's name is written only if it follows the name rule. A route that starts with
-is refused, because ssh would read it as an option (-oProxyCommand=…runs a command). hosts and profiles are checked the same way when netcap reads them, with the file and line of anything that breaks a rule - Comments in hosts and profiles are not kept
- On a new controller, run
netcap install <name>for each device to register that machine's own key