English · 日本語
この文書は host-setup.md の翻訳です。英語版と食い違うときは英語版が正です。
CLI は ssh 越しに端末側の agent を叩き、agent が動詞と引数を検査して本体に渡す。 最短の手順は README にある。
netcap install (この端末) と netcap install --ssh DEST (別の端末) は下のすべてをやる。このページの残りは、
中身の説明と、手で入れるときのためにある。
- OS を判定する (
uname、Windows なら PowerShell) - 端末側一式を向こうの一時ディレクトリへ送る。agent には CLI の版を書き込む。Windows なら
win/、 macOS と Linux ならmac/とlinux/の両方 (Linux のインストーラは agent をmac/から取る) - インストーラを流す:
sudo bash …/install.sh --boot off(netcap install --boot onなら--boot on。向こうの sudo パスワード)、Windows ならinstall.ps1(--with-download/--without-downloadなら-WithDownload/-WithoutDownload。ssh のユーザーが管理者であること)。終わったら一時ディレクトリを消す --sshで届く端末のときだけ: 手元に~/.ssh/netcapが無ければ作り、向こうに forced command の行 (下) を足す。鍵がもうあれば足さない。 この端末には鍵は要らない。netcap が agent を直接動かすhostsに端末を足す。コマンドラインで名前を渡さなければ、端末から流したときだけ 1 回聞く。そうでなければmeか ssh の宛先を名前にする
更新は netcap install <名前> をもう一度流す。起動時の挙動も設定し直す (渡さなければ --boot off) ので、
--boot on だった端末には --boot on を付ける。Windows の端末の WinDivert の選択 (下記) はフラグなしで残る。netcap get の agent 列に各端末の版が出る。
CLI の各リリースがどの版の agent と動くかは compatibility.ja.md にある。
netcap uninstall <名前> で、この管理する側が足したものを戻す。agent は最後の管理する側と一緒に外れる
(operations.ja.md)。--config-only はもう無い端末の登録だけ消す。
リポジトリの mac/、linux/、win/。brew で入れたなら $(brew --prefix)/opt/netcap/libexec/ の下。
brew を使わないなら clone か curl で取る。CLI は bin/netcap を PATH に通せば動く。
# git clone
git clone https://github.com/ken-ty/netcap.git ~/.local/share/netcap
# curl (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
# CLI を使うなら
ln -s ~/.local/share/netcap/bin/netcap ~/.local/bin/netcapcurl で入れると netcap --version は unknown になる。Windows でも curl と tar は標準で使える。
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 # CLI として使うならsudo bash mac/install.sh --boot on|off| パス | 役割 |
|---|---|
/Library/PrivilegedHelperTools/netcap-agent |
netcap が叩く入口。forced command にも使う |
/Library/PrivilegedHelperTools/netcap-netshape |
本体 (root で動く。pf + dummynet) |
/Library/PrivilegedHelperTools/netcap-check |
実測 (curl と ping だけなので root 不要) |
/etc/pf.anchors/netcap-netshape |
pf のルール |
/etc/netcap-netshape.conf |
既定の上限。netcap set が書く。無ければ既定は 1/1 |
/etc/sudoers.d/netcap-netshape |
インストーラを流した各ユーザーに、本体の決まった動詞だけ NOPASSWD |
/Library/LaunchDaemons/netcap-netshape.plist |
--boot on のときだけ |
/Library/PrivilegedHelperTools/netcap-netshape-expire.plist |
on --for が読み込み、期限に上限を外すジョブ。起動時には読み込まれない |
--boot onは起動時に既定の上限 (初期値 1/1。netcap setで変える) をかける。offは素のまま。 初めての--boot onはその場でもかける。インストーラーをもう一度動かしても、かかっている上限とその--forはそのまま- sudoers は
sudoを呼んだユーザーに、本体の決まった動詞だけを許す。別のユーザーならNETCAP_USER=<user>。 別のユーザーで流し直すと、そのユーザーが足され、ほかのユーザーは残る - 外すのは
sudo bash mac/uninstall.sh。1 人だけ外すならsudo bash mac/uninstall.sh --user(最後の 1 人が外れると全部外れる) - v0.5.0 までの旧名
ken-ty-netshapeは、install.shを流し直せば外れる。上限も外れるのでnetcap onでかけ直す - v0.14.0 までは
netcap-checkを/usr/local/binに置いていた。Homebrew を入れた Intel Mac では利用者が書ける場所。install.shとuninstall.shがそこから消す。Linux でも同じ
sudo bash linux/install.sh --boot on|off| パス | 役割 |
|---|---|
/usr/libexec/netcap/netcap-agent |
netcap が叩く入口。forced command にも使う |
/usr/libexec/netcap/netcap-netshape |
本体 (root で動く。tc) |
/usr/libexec/netcap/netcap-check |
実測 (root 不要) |
/etc/netcap-netshape.conf |
既定の上限。macOS と同じ |
/etc/sudoers.d/netcap-netshape |
インストーラを流した各ユーザーに、本体の決まった動詞だけ NOPASSWD |
/etc/systemd/system/netcap-netshape.service |
--boot on のときだけ |
- インターネットへの IPv4 の経路のインターフェース (
ip -4 route get 1.1.1.1) を絞る。下りはifbで受信を 折り返して絞る。tcとip(iproute2) が要る --boot・sudoers・NETCAP_USERは macOS と同じ。--boot onには systemd が要る。無いとき (コンテナなど) は--boot offにする。外すのはsudo bash linux/uninstall.sh(1 人だけなら--user)
管理者の PowerShell で:
powershell -NoProfile -ExecutionPolicy Bypass -File win\install.ps1C:\ProgramData\netcap\ に入る。agent、本体 (netshape.ps1)、netcap-check.ps1、uninstall.ps1 の 4 つ。
netcap set は既定の上限をそこの netshape.conf に書く。on --for は期限をそこの until に書き、
期限に上限を外すスケジュールタスク \netcap\expire を登録する (期限に電源が切れていた場合に備えて、起動時にも動く)。
外すには、管理者の PowerShell で:
powershell -NoProfile -ExecutionPolicy Bypass -File C:\ProgramData\netcap\uninstall.ps1mac との違いは 2 つ。下りは WinDivert があるときだけ絞る (下記。無ければ表では unsupported)。
on / off の状態は再起動しても残る (boot=keep)。
Windows の端末ごとに選択があり、端末に残り、netcap get の download 列に出る:
| download | どうしてそうなるか | netcap on がすること |
|---|---|---|
unset |
既定 | 端末から打つと WinDivert を入れるか聞く。--yes なら入れる。それ以外は上りだけ絞り、端末の名前を出す |
enabled |
その問いに y、on --yes、または netcap install <name> --with-download |
下りも絞る |
declined |
netcap install <name> --without-download (WinDivert も外す) |
聞かず、名前も出さずに上りだけ絞る |
use と protect は聞かない。unset の端末は上りだけ絞り、名前を出す。どちらのフラグも付けない
netcap install <name> は選択を変えない。手でなら install.ps1 -WithDownload か -WithoutDownload。入れるには x64 の
Windows (ARM64 は非対応: #111) と GitHub への接続が要り、どちらかが無ければ何も変えない。なぜ聞くのか、何と引き換えか:
ADR 0001。セキュリティソフトが何を言うか:
SECURITY.ja.md。
| パス | 役割 |
|---|---|
C:\ProgramData\netcap\windivert\ |
WinDivert 2.2.2 のリリース zip から取り出した WinDivert.dll、WinDivert64.sys、LICENSE。インストーラが取ってきて、SHA-256 が固定した値でなければ断る |
C:\ProgramData\netcap\netshape-down.ps1 |
下りの shaper。上限がかかっている間 (と、かかっている間の起動時に) SYSTEM としてスケジュールタスク \netcap\download から動く |
C:\ProgramData\netcap\download.mbit |
shaper が読む下りの速さ。on と set が書き、off が消す |
C:\ProgramData\netcap\download.state、download.log |
shaper が書く。WinDivert のハンドルを持っている間のプロセスと速さ、うまくいかなかった理由 |
C:\ProgramData\netcap\download.declined |
--without-download が書き、--with-download が消す |
off は shaper を終わらせるので何も待たせなくなるが、WinDivert のドライバは次の再起動まで読み込まれたまま。netcap は
自分からそのサービスを止めない。netcap unload-driver <name> は、何も使っていなければ今外す
(operations.ja.md)。
--without-download は shaper を止めて windivert フォルダを消す。uninstall.ps1 はほかと一緒に消す。
どちらでも、unload-driver で外していなければ、ドライバは次の再起動まで読み込まれたまま。netcap は自分からそのサービスを止めず、WinDivert が削除予定に
したサービスは、その再起動で Windows が消す。読み込まれたドライバのファイルは消せないので、WinDivert64.sys (と、それが
入ったフォルダ) は 1 回だけ動くタスク \netcap\cleanup に任せ、次の起動時に消す。それより前に入れ直すと、このタスクは取り消す。
どの動詞を許すかは、操作される端末の authorized_keys が決める。 netcap install は netcap 専用の鍵を作り、
端末側でその鍵を forced command に固定する。手でやるなら:
# 操作する側 (1 回だけ)
ssh-keygen -t ed25519 -f ~/.ssh/netcap -C netcap@<この機械> -N ""操作される Mac の ~/.ssh/authorized_keys に 1 行 (公開鍵は ~/.ssh/netcap.pub):
restrict,command="/Library/PrivilegedHelperTools/netcap-agent --allow 'status get check on off set'" ssh-ed25519 AAAA… netcap@<この機械>
操作される Linux では、agent のパスを /usr/libexec/netcap/netcap-agent にする。
操作される Windows では、管理者の鍵なら 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@<この機械>
unload-driver は低レベルの動詞 (operations.ja.md)。拒むなら外しておく。
netcap install は、それができる前に netcap が書いた行には足し、手で変えた行はそのままにする。
hosts の経路には、ふだん使っている ssh の Host を書く。~/.ssh/netcap があれば netcap はその鍵だけを差し出す
(IdentitiesOnly=yes) ので、上の行がある端末では agent しか動かない。これが無いと ssh は ssh-agent の鍵を先に差し出し、
自分の鍵も信頼している端末はそちらを受け入れて forced command を素通りする。
そのため端末には netcap の鍵が要る。hosts に手で足した端末には netcap install <名前> を実行する。
接続の共有も切る (ControlPath=none)。自分のログインで張った ControlMaster の接続に相乗りしても、
forced command を素通りするため。
--allowに並べた動詞しか通らない。読むだけにしたい端末は'status get check'にするrestrictでシェル・pty・転送を切る。agent は引数を空白で区切るだけで、シェルとして解釈しない- Windows には sudoers に当たる二段目が無く、forced command が唯一の関門になる
netcap doctorは ssh で届く各端末のファイルを読み、この機械の鍵の行にrestrictか forced command が欠けていれば 警告する (unrestricted)。置き換える行も表示する。鍵が無い端末はmissingになる。ssh で届く全端末がokなら 0 (この端末は鍵を使わないので-)、確かめられなかったのが届かない端末だけなら 3、それ以外は 1 で終わる- Windows の sshd は、
administrators_authorized_keysが UTF-16 (Windows PowerShell 5 の>>が書く形) だったり、 SYSTEM と Administrators 以外が書けたりすると、黙って無視する。UTF-8 で書き、新しく作ったファイルにはicacls <ファイル> /inheritance:r /grant:r "*S-1-5-18:F" "*S-1-5-32-544:F"をかける
--json の各行には os もある。hosts に書いたとおりの mac、linux、win で、届かない端末の行にも入る。
| reach | 意味 |
|---|---|
ok |
動いた |
unreachable |
ssh が届かない (終了コード 255) |
timeout |
時間内に応答が返らない |
no-agent |
端末側に agent が入っていない |
no-sudo |
端末側の sudoers に無い (mac、linux) |
denied |
端末側がその動詞を許していない (forced command の --allow) |
error |
届いたが、端末側が 0 以外で終わった |
| cap | 意味 |
|---|---|
on |
上限がかかっている |
off |
かかっていない |
partial |
上限の一部だけが残っている。pf のルールと dnctl の pipe が食い違っている (mac)、上りと下りのクラスの片方だけが残っている (linux)、netcap の QoS ポリシーの一部だけが残っている、タスクはあるのに下りの shaper が動いていない (win)。on か off を打ち直せば揃う |
? |
reach が ok でないので読めていない |
netcap install が書き込む。この列より前に入れた agent は -、clone から手で入れたものは unknown。
CLI と違っていたら netcap install <名前> を流す。
enabled、declined、unset のどれか (上)。macOS と Linux は WinDivert なしで下りも絞るので -。
reach が ok でないとき、端末から返った出力の最後の 1 行。全文は --json の raw にある。
reach が ok で、on --for でかけた上限が残っているときは残り時間 (あと 25m で外れる。英語では off in 25m)。
期限を過ぎて端末がまだ外していなければ 期限を過ぎた。まもなく外れる (due, lifting soon)。
--for より前の agent はこれを拒むので、そのことと更新の仕方 (netcap install <名前>) を出す。