Skip to content

Latest commit

 

History

History
244 lines (185 loc) · 15.9 KB

host-setup.ja.md

File metadata and controls

244 lines (185 loc) · 15.9 KB

端末側のセットアップ

English · 日本語

この文書は host-setup.md の翻訳です。英語版と食い違うときは英語版が正です。

CLI は ssh 越しに端末側の agent を叩き、agent が動詞と引数を検査して本体に渡す。 最短の手順は README にある。

netcap install がやること

netcap install (この端末) と netcap install --ssh DEST (別の端末) は下のすべてをやる。このページの残りは、 中身の説明と、手で入れるときのためにある。

  1. OS を判定する (uname、Windows なら PowerShell)
  2. 端末側一式を向こうの一時ディレクトリへ送る。agent には CLI の版を書き込む。Windows なら win/、 macOS と Linux なら mac/ と linux/ の両方 (Linux のインストーラは agent を mac/ から取る)
  3. インストーラを流す: sudo bash …/install.sh --boot off (netcap install --boot on なら --boot on。向こうの sudo パスワード)、Windows なら install.ps1 (--with-download / --without-download なら -WithDownload / -WithoutDownload。ssh のユーザーが管理者であること)。終わったら一時ディレクトリを消す
  4. --ssh で届く端末のときだけ: 手元に ~/.ssh/netcap が無ければ作り、向こうに forced command の行 (下) を足す。鍵がもうあれば足さない。 この端末には鍵は要らない。netcap が agent を直接動かす
  5. 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/netcap

curl で入れると 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 として使うなら

macOS

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 でも同じ

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)

Windows

管理者の PowerShell で:

powershell -NoProfile -ExecutionPolicy Bypass -File win\install.ps1

C:\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.ps1

mac との違いは 2 つ。下りは WinDivert があるときだけ絞る (下記。無ければ表では unsupported)。 on / off の状態は再起動しても残る (boot=keep)。

Windows の下り: WinDivert

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 — その端末に届いて、頼めたか

reach 意味
ok 動いた
unreachable ssh が届かない (終了コード 255)
timeout 時間内に応答が返らない
no-agent 端末側に agent が入っていない
no-sudo 端末側の sudoers に無い (mac、linux)
denied 端末側がその動詞を許していない (forced command の --allow)
error 届いたが、端末側が 0 以外で終わった

cap — いま上限がかかっているか (status のみ。実物から読む)

cap 意味
on 上限がかかっている
off かかっていない
partial 上限の一部だけが残っている。pf のルールと dnctl の pipe が食い違っている (mac)、上りと下りのクラスの片方だけが残っている (linux)、netcap の QoS ポリシーの一部だけが残っている、タスクはあるのに下りの shaper が動いていない (win)。on か off を打ち直せば揃う
? reach が ok でないので読めていない

agent — agent の版 (get のみ)

netcap install が書き込む。この列より前に入れた agent は -、clone から手で入れたものは unknown。 CLI と違っていたら netcap install <名前> を流す。

download — WinDivert の選択 (get のみ、Windows)

enabled、declined、unset のどれか (上)。macOS と Linux は WinDivert なしで下りも絞るので -。

note — うまくいかなかった理由、または上限が外れる時刻

reach が ok でないとき、端末から返った出力の最後の 1 行。全文は --json の raw にある。

reach が ok で、on --for でかけた上限が残っているときは残り時間 (あと 25m で外れる。英語では off in 25m)。 期限を過ぎて端末がまだ外していなければ 期限を過ぎた。まもなく外れる (due, lifting soon)。 --for より前の agent はこれを拒むので、そのことと更新の仕方 (netcap install <名前>) を出す。