English · 日本語
The CLI calls the agent on each device over ssh; the agent checks the verb and arguments and hands them to the shaper. The shortest path is in the README.
netcap install (this machine) and netcap install --ssh DEST (another device) do everything below, so the rest of this
page is for reference and for setting a device up by hand.
- Tell the OS (
uname, or PowerShell for Windows) - Copy the device side to a temporary directory there, with the CLI's version written into the agent:
win/for Windows, ormac/andlinux/together for macOS and Linux (the Linux installer takes the agent frommac/) - Run the installer:
sudo bash …/install.sh --boot off(--boot onwithnetcap install --boot on; the device's sudo password), orinstall.ps1on Windows (-WithDownload/-WithoutDownloadwith--with-download/--without-download; the ssh user must be an Administrator). Then remove the temporary directory - Only for a device reached with
--ssh: create~/.ssh/netcapon this machine if missing, and add its forced-command line on the device (below) unless the key is already there. This machine needs no key: netcap runs its agent directly - Add the device to
hosts. Without a name on the command line, it asks once when run from a terminal; otherwise it takesme, or the ssh destination
To update a device, run netcap install <name> again. That sets the boot behavior again too (--boot off unless given),
so add --boot on for a device that had it. A Windows device keeps its WinDivert choice (below) without a flag. The agent column of netcap get shows each device's version.
Which agent versions each CLI release works with: compatibility.md.
netcap uninstall <name> reverses what this controller added; the agent goes with the last controller
(operations.md). --config-only just forgets a device that is gone.
mac/, linux/, and win/ in this repository. If you installed with brew, under $(brew --prefix)/opt/netcap/libexec/.
Without brew, get them with clone or curl. The CLI works once bin/netcap is on your PATH.
# git clone
git clone https://github.com/ken-ty/netcap.git ~/.local/share/netcap
# curl (without git)
mkdir -p ~/.local/share/netcap
curl -fsSL https://github.com/ken-ty/netcap/archive/refs/tags/v0.16.0.tar.gz \
| tar xz --strip-components 1 -C ~/.local/share/netcap
# to use the CLI
ln -s ~/.local/share/netcap/bin/netcap ~/.local/bin/netcapInstalled with curl, netcap --version prints unknown. curl and tar are also available on Windows out of the box.
curl.exe -fsSL -o netcap.zip https://github.com/ken-ty/netcap/archive/refs/tags/v0.16.0.zip
tar -xf netcap.zip
cd netcap-0.16.0
python bin\netcap --version # to use it as the CLIsudo bash mac/install.sh --boot on|off| Path | Role |
|---|---|
/Library/PrivilegedHelperTools/netcap-agent |
The entry point netcap calls. Also used as the forced command |
/Library/PrivilegedHelperTools/netcap-netshape |
The shaper (runs as root; pf + dummynet) |
/Library/PrivilegedHelperTools/netcap-check |
Measurement (only curl and ping, so no root needed) |
/etc/pf.anchors/netcap-netshape |
pf rules |
/etc/netcap-netshape.conf |
The default cap. Written by netcap set; without it the default is 1/1 |
/etc/sudoers.d/netcap-netshape |
NOPASSWD for each user who ran the installer, limited to the shaper's fixed verbs |
/Library/LaunchDaemons/netcap-netshape.plist |
Only with --boot on |
/Library/PrivilegedHelperTools/netcap-netshape-expire.plist |
The job on --for loads to lift the cap at the deadline. Not loaded at boot |
--boot onapplies the default cap at boot (initially 1/1; change it withnetcap set).offleaves the device as is. The first--boot onalso applies it now; running the installer again leaves the cap in effect, and its--for, as they are- sudoers allows only the shaper's fixed verbs, for the user who ran
sudo. For a different user, passNETCAP_USER=<user>. Running it again as another user adds that user and keeps the others - To remove:
sudo bash mac/uninstall.sh. To remove only one user:sudo bash mac/uninstall.sh --user(everything goes with the last user) - The old name
ken-ty-netshape(up to v0.5.0) is removed by runninginstall.shagain. That also removes the cap, so reapply it withnetcap on - Up to v0.14.0,
netcap-checkwas in/usr/local/bin, which the user can write on an Intel Mac with Homebrew.install.shanduninstall.shremove it from there, on Linux too
sudo bash linux/install.sh --boot on|off| Path | Role |
|---|---|
/usr/libexec/netcap/netcap-agent |
The entry point netcap calls. Also used as the forced command |
/usr/libexec/netcap/netcap-netshape |
The shaper (runs as root; tc) |
/usr/libexec/netcap/netcap-check |
Measurement (no root needed) |
/etc/netcap-netshape.conf |
The default cap, as on macOS |
/etc/sudoers.d/netcap-netshape |
NOPASSWD for each user who ran the installer, limited to the shaper's fixed verbs |
/etc/systemd/system/netcap-netshape.service |
Only with --boot on |
- Caps the interface of the IPv4 route to the internet (
ip -4 route get 1.1.1.1). Download is capped by redirecting ingress throughifb. Needstcandip(iproute2) --boot, sudoers, andNETCAP_USERwork as on macOS.--boot onneeds systemd; without it (a container, for example), use--boot off. To remove:sudo bash linux/uninstall.sh(--userfor one user)
In an Administrator PowerShell:
powershell -NoProfile -ExecutionPolicy Bypass -File win\install.ps1Installs into C:\ProgramData\netcap\: the agent, the shaper (netshape.ps1), netcap-check.ps1, and uninstall.ps1.
netcap set writes the default cap to netshape.conf there. on --for writes its deadline to until there and
registers the scheduled task \netcap\expire, which lifts the cap at the deadline (it also runs at startup, in case the
machine was off then). To remove, in an Administrator PowerShell:
powershell -NoProfile -ExecutionPolicy Bypass -File C:\ProgramData\netcap\uninstall.ps1Two differences from mac: download is capped only with WinDivert (below; otherwise unsupported in the table), and
the on / off state survives reboots (boot=keep).
Each Windows device has a choice, kept on the device and shown in the download column of netcap get:
| download | How it got there | What netcap on does |
|---|---|---|
unset |
the default | From a terminal, asks whether to install WinDivert; with --yes, installs it. Otherwise caps upload only and names the device |
enabled |
y to that question, on --yes, or netcap install <name> --with-download |
Caps download too |
declined |
netcap install <name> --without-download, which also removes WinDivert |
Caps upload only, without asking or naming the device |
use and protect never ask: they cap upload only on an unset device and name it. netcap install <name> without
either flag keeps the choice. By hand: install.ps1 -WithDownload or -WithoutDownload. Installing needs x64 Windows
(ARM64 is not supported: #111) and a connection to GitHub, and changes nothing when either is missing. Why it is asked for and what it costs:
ADR 0001; what security software may say about it:
SECURITY.md.
| Path | Role |
|---|---|
C:\ProgramData\netcap\windivert\ |
WinDivert.dll, WinDivert64.sys, and LICENSE from the WinDivert 2.2.2 release zip, which the installer fetches and refuses unless its SHA-256 is the pinned one |
C:\ProgramData\netcap\netshape-down.ps1 |
The download shaper. Runs as SYSTEM from the scheduled task \netcap\download while a cap is on (and at startup while it is on) |
C:\ProgramData\netcap\download.mbit |
The download rate the shaper reads. Written by on and set, removed by off |
C:\ProgramData\netcap\download.state, download.log |
Written by the shaper: its process and rate while it holds the WinDivert handle, and what went wrong |
C:\ProgramData\netcap\download.declined |
Written by --without-download, removed by --with-download |
off ends the shaper, so nothing is held back, but the WinDivert driver stays loaded until the next reboot:
netcap never stops its service on its own. netcap unload-driver <name> unloads it now when nothing uses it
(operations.md).
--without-download stops the shaper and removes the windivert folder; uninstall.ps1 removes it with the rest.
The driver stays loaded until the next reboot either way, unless unload-driver unloaded it: netcap never stops its service by itself, and
Windows removes the service, which WinDivert marks for deletion, at that reboot. A loaded driver's file cannot be deleted,
so WinDivert64.sys (and the folder it is in) is left to the one-time task \netcap\cleanup, which removes it at the next
startup. Installing again before that calls the task off.
Which verbs are allowed is decided by the authorized_keys of the device being controlled. netcap install creates a key
just for netcap and pins it to a forced command on the device. By hand:
# on the controlling machine (once)
ssh-keygen -t ed25519 -f ~/.ssh/netcap -C netcap@<this-machine> -N ""Add one line to ~/.ssh/authorized_keys on the controlled Mac (the public key is ~/.ssh/netcap.pub):
restrict,command="/Library/PrivilegedHelperTools/netcap-agent --allow 'status get check on off set'" ssh-ed25519 AAAA… netcap@<this-machine>
On a controlled Linux device, use /usr/libexec/netcap/netcap-agent as the agent path.
On a controlled Windows device, for an administrator's key, add to C:\ProgramData\ssh\administrators_authorized_keys:
restrict,command="powershell -NoProfile -ExecutionPolicy Bypass -File C:\ProgramData\netcap\netcap-agent.ps1 --allow 'status get check on off set unload-driver'" ssh-ed25519 AAAA… netcap@<this-machine>
unload-driver is a low-level verb (operations.md); leave it out to refuse it.
netcap install adds it to a line that netcap wrote before it existed, and leaves a line changed by hand as it is.
Put your usual ssh Host in the route column of hosts. Once ~/.ssh/netcap exists, netcap offers only that key
(IdentitiesOnly=yes), so a device that has the line above runs nothing but the agent. Without it, ssh would offer the keys
in ssh-agent first, and a device that also trusts your own key would take that one and skip the forced command.
So a device must have the netcap key: for one you added to hosts by hand, run netcap install <name>.
netcap also turns off connection sharing (ControlPath=none): a shared ControlMaster connection from your own login
would skip the forced command too.
- Only the verbs listed in
--allowget through. For a read-only device, use'status get check' restrictdisables the shell, pty, and forwarding. The agent only splits arguments on whitespace and never interprets them as a shell- Windows has no second gate like sudoers, so the forced command is the only gate
netcap doctorreads the file on each device reached over ssh and warns about a line for this machine's key that lacksrestrictor the forced command (unrestricted), printing the line to put in its place. A device without the key showsmissing. It exits with 0 when every device reached over ssh isok(this machine shows-: it uses no key), 3 when the only devices it could not check were out of reach, and 1 otherwise- Windows' sshd silently ignores
administrators_authorized_keysif it is UTF-16 (what>>writes in Windows PowerShell 5) or writable by anyone but SYSTEM and Administrators. Write UTF-8, and give a new fileicacls <file> /inheritance:r /grant:r "*S-1-5-18:F" "*S-1-5-32-544:F"
Each row of --json also has os: mac, linux, or win, as written in hosts, also for a device out of reach.
| reach | Meaning |
|---|---|
ok |
It worked |
unreachable |
ssh could not reach it (exit code 255) |
timeout |
No response in time |
no-agent |
The agent is not installed on the device |
no-sudo |
Not in the device's sudoers (mac, linux) |
denied |
The device does not allow that verb (--allow of the forced command) |
error |
Reached, but the device exited with non-zero |
| cap | Meaning |
|---|---|
on |
A cap is in effect |
off |
No cap |
partial |
Only part of the cap is in place: pf rules and dnctl pipes disagree (mac), only one of the upload and download classes is left (linux), or only some of netcap's QoS policies are left, or the download shaper is not running while its task is (win). Running on or off again brings them back in line |
? |
Not read, because reach is not ok |
Written in by netcap install. - for an agent installed before this column existed; unknown for one installed by hand from a clone.
If it differs from the CLI, run netcap install <name>.
enabled, declined, or unset (above). - on macOS and Linux, which cap download
without it.
When reach is not ok, the last line of the device's output. The full output is in raw of --json.
When reach is ok and a cap set with on --for is pending, the time left (off in 25m), or due, lifting soon once the
deadline has passed and the device has yet to lift it. An agent from before --for refuses it; the note then says so and
how to update it (netcap install <name>).