English: README.en.md

稼働中に TCP/UDP の転送を追加・変更・削除・問い合わせできる L4 フォワーダ。 制御は HTTP API で行い、管理 UI は TCP-UDP-rproxy-ui にある。

はじめての方は docs/GUIDE.md（設定と運用の手引き：設定ファイルの書き方・制御 API の使い方・更新・監視・レシピを、やりたいこと別に）。

構成図（全体・モジュール・接続の流れ・ルールの状態）は docs/architecture/。

systemd で動く Linux に、root で実行する。Debian / Ubuntu では apt リポジトリから、それ以外では GitHub Release の静的リンクのバイナリ（x86_64 / aarch64 / armv7）を入れ、ユーザー・設定・ユニットを作って起動する。

curl -fsSL https://raw.githubusercontent.com/max3584/rproxy-api/master/scripts/install.sh | bash -s -- \
  --api-addr 127.0.0.1 --database-url 'mysql://rproxy:[email protected]:3306/rproxy'

• 最後に UI の .env.local に設定する RPROXY_API_URL と RPROXY_API_TOKEN の取り出し方を表示する
• 制御 API の既定のポート 8080 が使われていれば、初回だけ 8081〜8099 の空きを選ぶ
• ログは /var/log/rproxy/rproxy.<日付>.log（rproxy が日ごとに分けて古いものを消すので logrotate は不要）。--log-file - で journald に出す
• もう一度実行するとアップグレード（設定とトークンは残し、指定したオプションだけを書き換える）
• source_ip: transparent の権限（CAP_NET_ADMIN）はユニットで与える。戻りのパケットのポリシールーティングは --transparent-clients <CIDR> --transparent-iface <IF> で入れる（下の「送信元 IP の引き渡し」）
• --uninstall（--purge で設定・トークン・ログも消す）。オプションの一覧は install.sh --help。必要な権限は docs/PERMISSIONS.md

apt リポジトリから入れられる（amd64 / arm64 / armhf）。同じリポジトリに管理 UI の rproxy-ui もある（sudo apt install rproxy-api rproxy-ui。UI は Node.js 22.23.4 以上（24 なら 24.22.1 以上）が要る。arm64 は NodeSource の nodejs で動き、Raspberry Pi なら 64 ビットの OS を勧める。TCP-UDP-rproxy-ui の README）。

sudo curl -fsSLo /usr/share/keyrings/rproxy-archive-keyring.gpg https://max3584.github.io/rproxy-api/rproxy-archive-keyring.gpg
echo "deb [signed-by=/usr/share/keyrings/rproxy-archive-keyring.gpg] https://max3584.github.io/rproxy-api stable main" \
  | sudo tee /etc/apt/sources.list.d/rproxy-api.list
sudo apt update && sudo apt install rproxy-api

インストールしただけでは起動しない。/etc/rproxy/rproxy.env を書き換えてから sudo systemctl enable --now rproxy-api で起動する。 API のトークンはインストール時に /etc/rproxy/tokens に生成される（UI の RPROXY_API_TOKEN に設定する）。 パッケージの中身と、リポジトリの公開の仕組みは docs/APT.md。

バックアップと復旧（何を取るか、DB と設定ファイルの取り方、戻す順番と確かめ方、新しいホストへの移し方、DB なしで動かす方法）は docs/BACKUP.md。

性能の改善の記録（採用したもの・採用しなかったものとその理由、測り方の注意）は docs/PERFORMANCE.md。

設定は環境変数で行う。起動ディレクトリに .env があれば読み込む（例は .env.example）。 同じ項目をコマンドライン引数（--api-port など）で指定した場合は、引数が優先される。

cargo build --locked --release
cp .env.example .env   # 値を環境に合わせて書き換える
./target/release/rproxy-api

メモリの割り当ては既定で libc の malloc（リリースのバイナリは musl の malloc。メモリが最も少ない）。L7（HTTP/2・小さいリクエストの多い HTTP）で CPU を減らしたいときは、mimalloc でビルドできる：cargo build --locked --release --features alloc-mimalloc（C コンパイラでビルドする）。手元の測定では HTTP/2 と小さい HTTP のリクエストが 20〜30% 速く、CPU 秒あたりの処理が 25〜170% 増えるかわりに、起動直後のメモリが約 6 MiB、負荷時のピークが 15〜40 MiB 増える。

systemd で動かす場合は EnvironmentFile=/etc/rproxy/rproxy.env で同じ内容を渡せる。

v0.4 で足した項目（どれも動く。ルールに付ける設定と global の項目は docs/API.md の「v0.4 の設定」。制御 API の守りは「制御 API の守り」、再起動なしの更新・自動更新は docs/UPGRADE.md）：

RPROXY_API_ADDR に loopback 以外を含める場合は、トークンファイルと TLS 証明書の指定が必須。どれかが欠けていると起動しない。

設定のエラー（値の誤り、存在しないパス、ファイルの中身の誤り）では起動しない。 それ以外の環境の問題では、使えない部分だけを止めて起動を続ける（ログに "event":"degraded" と part を出す）。

既定では、SIGTERM（systemctl stop）ですべての転送をすぐに止める（今の接続も切る）。前にロードバランサや VIP があるときや、今の接続を終わらせてから止めたいときは、RPROXY_SHUTDOWN_DELAY・RPROXY_SHUTDOWN_DRAIN を /etc/rproxy/rproxy.env に書く：

1. SIGTERM が来たら /readyz を 503 draining にし、DELAY の間は今までどおり受け付ける（ヘルスチェックで外れるのを待つ）。
2. 待ち受けを閉じ（新しい接続・UDP のセッションを受けない）、今の接続が終わるのを DRAIN まで待つ。HTTP は処理中のリクエストに Connection: close（HTTP/2 は GOAWAY）を付けて閉じ、アイドルの接続はすぐ閉じる。UDP の今のセッションは続く。
3. 残りを切って終わる。2 回目の SIGTERM・Ctrl-C ではすぐに止める。

その間、制御 API の読むだけの要求（GET・/metrics）は答え、変更は 503 shutting_down で断る。

systemd の TimeoutStopSec（既定 90 秒）は DELAY + DRAIN + 5 秒 より長くしておく。systemctl restart もこの分だけ遅くなるので、バイナリの更新には再起動なしの更新（SIGUSR2、docs/UPGRADE.md）を使う。Kubernetes では rproxy-gateway が 5s・25s を渡す。

API の詳細は docs/API.md を参照。

TOKEN=$(sudo head -1 /etc/rproxy/tokens)   # /etc/rproxy は root:rproxy 750

# 転送を追加
curl -H "Authorization: Bearer $TOKEN" -X POST http://127.0.0.1:8080/rules \
  -d '{"protocol":"tcp","listen_addr":"0.0.0.0","listen_port":8888,"remote_addr":"192.168.1.2","remote_port":8080}'

# 一覧
curl -H "Authorization: Bearer $TOKEN" http://127.0.0.1:8080/rules

# 転送先を変更（新しい接続から即時に反映）
curl -H "Authorization: Bearer $TOKEN" -X PATCH http://127.0.0.1:8080/rules/tcp/0.0.0.0/8888 \
  -d '{"remote_addr":"192.168.1.3","remote_port":8081}'

# 宛先を複数に（balance: round_robin / least_conn / failover。health_check で生死を確かめる）
curl -H "Authorization: Bearer $TOKEN" -X POST http://127.0.0.1:8080/rules \
  -d '{"protocol":"tcp","listen_addr":"0.0.0.0","listen_port":5432,
       "targets":[{"addr":"10.0.0.11","port":5432},{"addr":"10.0.0.12","port":5432},{"addr":"10.0.0.13","port":5432,"backup":true}],
       "balance":"least_conn","health_check":{"interval":"10s"}}'

# IPv4 と IPv6 を 1 つのルールで待ち受ける（extra_listen_addrs。0.0.0.0 と :: も並べられる）
curl -H "Authorization: Bearer $TOKEN" -X POST http://127.0.0.1:8080/rules \
  -d '{"protocol":"tcp","listen_addr":"203.0.113.5","extra_listen_addrs":["2001:db8::5"],"listen_port":443,
       "remote_addr":"10.0.0.20","remote_port":443}'

# 停止（既存の接続も切断。?drain_secs=30 で終了を待つ）
curl -H "Authorization: Bearer $TOKEN" -X DELETE http://127.0.0.1:8080/rules/tcp/0.0.0.0/8888

RPROXY_CONFIG に設定ファイル（YAML か JSON）かそのディレクトリを指定すると、起動時にそのルールを開始します（DB からの復元より前）。ファイルを書き換えると、再起動なしで差分だけを反映します（変わっていないルールの接続は切りません。誤りがあれば反映せず、GET /config とログで知らせます）。API と画面からは変更・削除できないので、rproxy 経由で Web UI を公開するルールに向いています（誤って消して、画面に入れなくなることがありません）。

例（contrib/rproxy.example.yaml）：dashboard.proxy.home だけを、社内のネットワークから 443 で受け付けます。

• tls.routes と tls.unmatched: reject：ほかの名前や SNI なしの接続は、証明書を返す前に切る（Traefik の Host(...) のルールにあたる）
• allow_from：範囲外の送信元は TLS より前に切る
• Web UI（rproxy-ui のパッケージ）は既定で 127.0.0.1:3000 だけで待ち受ける。NEXTAUTH_URL は https://dashboard.proxy.home にする

SNI やサーバ名は、クライアントが自由に名乗れます。名前での振り分けだけではアクセス制限にならないので、allow_from、mTLS（client_auth）、Web UI のログインを組み合わせてください。

Traefik から移るときは、rproxy-traefik-convert（crates/rproxy-traefik。.deb に入っている）で Traefik の設定（静的・動的な設定、Docker のラベル）をこの設定ファイルに変換できます。変換できなかった設定は出力の先頭と標準エラーに一覧されます（docs/MIGRATING-FROM-TRAEFIK.md）。

systemd で動かす例は contrib/rproxy-api.service にあります（80 / 443 などのために CAP_NET_BIND_SERVICE を付ける）。

設定ファイルを書き換えたら、反映する前に rproxy-api --check-config で確かめられます（nginx の nginx -t にあたる）。起動時・再読み込みと同じ検証（書式、ルールの値、待ち受けの重なり、制御 API との重なり、証明書・鍵・CA のファイルと期限、global と認証などの秘密のファイル）をして、問題がなければ 0、誤りがあれば 1 で終わります。待ち受けも DB も開かず、動いている rproxy にも触りません。

rproxy-api --check-config                            # RPROXY_CONFIG（/etc/rproxy/rproxy.env など）のファイル
rproxy-api --check-config /etc/rproxy/conf.d         # ファイルかディレクトリを指定
rproxy-api --check-config /etc/rproxy/rproxy.yaml --check-config-format json   # スクリプト向け
rproxy-api --check-config /etc/rproxy/rproxy.yaml && systemctl reload rproxy-api
rproxy-api --check-config /etc/rproxy/rproxy.yaml --diff --diff-token-file /etc/rproxy/admin.token   # 動いている rproxy と比べた差分も出す

• 誤り：ファイル・ルール（rproxy.yaml rule #2 など）ごとに理由を出す。最初の 1 つで止めず、すべて出す
• 警告：期限が近い証明書（RPROXY_CERT_WARN_DAYS）、この版や権限で動かせない設定（起動すると failed になる）、rproxy のユーザーが読めないかもしれないファイル（所有者とモードからの判断）、API のルールなら断るファイル（証明書のストア・ACME の保存先・秘密のファイル、OIDC の client secret の使い回し。v0.4.17、docs/API.md の「API のルールが指せるファイル」）
• JSON：{"ok": false, "path": "...", "files": [...], "rules": 3, "errors": [{"rule": "rproxy.yaml rule #2", "message": "..."}], "warnings": [...]}
• 名前解決はしない（転送先の名前が引けるかは、起動したときに分かる）
• 設定ファイルが指定されていなければ、確かめるものがないので 0 で終わる
• --diff：検証に通ったら、動いている rproxy に POST /config/plan で問い合わせ、反映すると作る・変える・消すルールを 1 行ずつ出す（+ / ~ / -、再起動が要る global は !）。問い合わせ先の既定は RPROXY_API_SOCKET、なければ制御 API（--diff-api で指定）。トークンは admin のスコープ（--diff-token-file）。docs/API.md の「変更前の差分」

パッケージ（と install.sh）の systemd のユニットは、systemctl reload rproxy-api で先にこの確認をします。誤りがあれば reload は失敗し（journalctl -u rproxy-api に理由）、rproxy には何も送りません。そのときは、トークンや証明書の読み直しも行われないので、設定ファイルを直してから reload してください。

systemctl reload は合図を送るだけなので、反映できたかはコマンドの結果では分かりません。スクリプトで結果がほしいときは、制御 API の POST /config/reload を使います。読み直して反映し、追加・変更・削除の数（誤りがあれば何も変えずに 400 と理由）を返します。

curl --unix-socket /run/rproxy/api.sock -H "Authorization: Bearer $ADMIN_TOKEN" -X POST http://localhost/config/reload
# {"added":1,"removed":0,"changed":1,"unchanged":3,"failed":0,"restart_needed":[],"files":["/etc/rproxy/rproxy.yaml"],"rules":5,"warnings":[]}

• admin のスコープを持つトークンだけが使えます（UI 用の rules:read / rules:write では使えない）
• 既定では Unix ソケット（RPROXY_API_SOCKET）からだけ受け付けます。TCP の制御 API から使うなら RPROXY_API_RELOAD_UNIX_ONLY=false
• POST /config/reload?dry_run=true は反映せずに、反映したら何が変わるか（changes。ルールごとの diff と、接続を切らずに変えられるか（change：in_place / recreate））を返します。ルールの POST / PATCH / DELETE と PUT /rulesets/{name} にも ?dry_run=true があります
• ファイルの変化の検知・SIGHUP と同じ処理で、同時には動きません

ルールごとに、中身をどう扱うかを選べます（詳細は docs/API.md、用途別の設定例は docs/PROFILES.md）。

証明書はファイルで指定するか、ACME（Let's Encrypt など。HTTP-01・TLS-ALPN-01・DNS-01（PowerDNS・RFC 2136・acme-dns・汎用の REST））で rproxy に取らせます（{acme: <resolver>, domains: [...]}、docs/ACME.md）。制御 API の PUT /certs/{name} で証明書と鍵を渡して保存し、ルールから {cert: <name>} で使うこともできます（v0.4.2、docs/API.md の「証明書の API」）。ファイルが変わると自動で読み直すので（RPROXY_CERT_CHECK_SECS）、certbot や cert-manager で更新した証明書がそのまま使われます（SIGHUP ですぐに読み直すこともできます）。ACME で取った証明書も期限の前に自分で更新し、同じ仕組みで差し替えます。DNS-01 の秘密は、別のユーザーで動かす補助プロセス rproxy-api acme-helper（rproxy-acme-helper.service）だけに持たせることもできます。source_ip: proxy_v2 と組み合わせると、SNI・ALPN・クライアント証明書の CN を PROXY v2 の TLV で転送先に渡します。

CrowdSec の判定で止める（L7 の crowdsec ミドルウェア、L4 のルールの crowdsec: true、AppSec）だけでなく、CrowdSec のエージェントに rproxy のログを読ませて、rproxy を通るアクセスから攻撃を見つけて ban させることもできます。パーサー・シナリオ・acquis は contrib/crowdsec/（.deb では /usr/share/rproxy-api/crowdsec/）、手順は docs/CROWDSEC.md。本物の CrowdSec との一周（検知 → ban → rproxy で止める）は CI（interop の crowdsec ジョブ）で確かめています。

ルールごとに source_ip で選ぶ（TLS を終端しない tls.routes[] は route ごとにも proxy・proxy_v1・proxy_v2 を選べる。v0.4.13）。PROXY protocol とは何か、どれを選ぶか、転送先（Postfix・Dovecot・nginx・ingress-nginx など）の設定の例は docs/SOURCE-IP.md。

rproxy の前にロードバランサなどがいて PROXY protocol を付けて送ってくるときは、ルールの proxy_protocol でヘッダを受け取る（v0.4.13。tcp のルール、v0.4.16 から udp のルールも：データグラムごとの PROXY v2）。信じるのは from に書いた前段からのヘッダだけで、allow_from・limits・ログ・X-Forwarded-For・上の source_ip などはヘッダのクライアントで動く。前段のアドレスはログの proxy_peer。

"proxy_protocol": {"from": ["10.2.0.0/16", "172.16.10.19/32"], "required": true}

required（既定 true）は from からの接続がヘッダを付けてこなければ断る。from の外からヘッダで始まる接続も断る。詳しくは docs/SOURCE-IP.md と docs/API.md の「PROXY protocol を受け取る」。

transparent を使うには、rproxy に CAP_NET_ADMIN を与え、転送先からの戻りパケットを rproxy のホスト自身で受け取るポリシールーティングを設定する。 apt・install.sh で入れた場合は、ユニットが CAP_NET_ADMIN を与えているので権限の設定は要らない。ポリシールーティング（下の 1）は install.sh でまとめて入れられる（起動時に毎回設定する rproxy-transparent-routing.service を作る）。

install.sh --transparent-clients 10.0.1.0/24 --transparent-iface eth1
rproxy-transparent-routing status   # 入っている ip rule / ip route を見る

手で起動する場合（systemd を使わない場合）は、root で動かすかバイナリに権限を付ける。権限の一覧は docs/PERMISSIONS.md。

setcap cap_net_bind_service,cap_net_admin+ep ./target/release/rproxy-api

戻りパケットの受け取り方は2通りある。

1. クライアントのアドレス範囲が決まっている場合（scripts/test-transparent.sh で動作確認済み）。 転送先側のインターフェースから届いた、クライアント宛てのパケットをローカル扱いにする。

   ip route add local 10.0.1.0/24 dev lo table 100   # クライアントのアドレス範囲
   ip rule add iif <転送先側のインターフェース> lookup 100

2. クライアントのアドレス範囲が決まっていない場合（ROUTING=iptables / ROUTING=nft の scripts/test-transparent.sh で動作確認済み）。 rproxy の transparent ソケット宛てのパケットだけに印を付けて、ローカル扱いにする。

   # iptables
   iptables -t mangle -A PREROUTING -p tcp -m socket --transparent -j MARK --set-mark 1
   iptables -t mangle -A PREROUTING -p udp -m socket --transparent -j MARK --set-mark 1
   # または nftables
   nft add table ip rproxy
   nft add chain ip rproxy prerouting '{ type filter hook prerouting priority mangle; }'
   nft add rule ip rproxy prerouting socket transparent 1 meta mark set 1
   
   ip rule add fwmark 1 lookup 100
   ip route add local 0.0.0.0/0 dev lo table 100

   再起動後も残すには、nftables なら /etc/nftables.conf に、ip rule / ip route は rproxy-transparent-routing と同じように起動時に設定する。

どちらの場合も、転送先のデフォルトゲートウェイを rproxy のホストにする（または転送先側でクライアント宛ての経路を rproxy に向ける）必要がある。 使えるかどうかは GET /capabilities で確認できる。

scripts/test-transparent.sh は、root 権限なしでユーザー名前空間とネットワーク名前空間の中に「クライアント・rproxy・転送先」の構成を作る。そのうえで、proxy と transparent のそれぞれについて、TCP と UDP で転送先から見える送信元アドレスを確かめる（cargo build のあとに実行）。

1 行 1 イベントの JSON。クライアントが決める長い項目（パス・クエリ・User-Agent・Host・SNI）は 2,048 バイトで切る（...[truncated]、v0.4.20）。共通の項目は timestamp、level、event、rule（tcp/0.0.0.0:8888 の形）。既定の RPROXY_LOG_LEVEL=info で出るもの（debug だけのものは最後の行）。SIEM・CrowdSec で拾うなら、まず audit・conn.denied・http.access・tls.error・target.down・cert.*・crowdsec.error。各項目は docs/API.md。

cargo test     # 単体テスト（src/）と、実際にソケットを使う結合テスト（tests/。一覧は docs/TESTING.md）
cargo clippy --all-targets

rproxy-api は glacierx の rproxy（MIT License）を出発点に始めた。 今は制御 API・TLS・DTLS・STARTTLS・送信元 IP の引き渡しなどを含め、コードはすべて作り直した独立したプロジェクトで、元のプロジェクトとは別に開発している。 TCP の双方向の転送ループと、UDP のクライアントごとのセッションという設計は元のプロジェクトに由来する（src/l4/tcp.rs と src/l4/udp.rs の先頭に記載）。

MIT License。元のプロジェクトの著作権表示も含めて LICENSE を参照。