TinyChannels Edge - User Manual

TinyChannels Edge - ユーザーマニュアル

Secure communication relay for the TinyChannels platform.

TinyChannels プラットフォームのセキュア通信リレー。

Overview

概要

TinyChannels Edge acts as a relay node in the TinyChannels secure communication platform. It facilitates WebTransport-based connections between Ends, enabling real-time encrypted communication channels authorized by the Authorization Manager (Center).

TinyChannels Edge は、TinyChannels セキュア通信プラットフォームにおけるリレーノードです。エンド間の WebTransport ベースの接続を仲介し、認可マネージャー（Center）によって認可されたリアルタイム暗号化通信チャネルを実現します。

Key Features

主な機能

• QUIC/WebTransport-based secure relay
• Mutual TLS authentication with Authorization Manager
• Dynamic channel authorization and routing
• Cross-platform support (macOS, Windows, Linux)
• GUI utility for registration and daemon management
• Machine-bound private key encryption

• QUIC/WebTransport ベースのセキュアリレー
• 認可マネージャーとの相互 TLS 認証
• 動的なチャネル認可とルーティング
• クロスプラットフォーム対応（macOS、Windows、Linux）
• 登録・デーモン管理用 GUI ユーティリティ
• マシン固有の秘密鍵暗号化

Architecture

アーキテクチャ

The Edge consists of three main components:

Edge は以下の 3 つのコンポーネントで構成されます：

System Requirements

システム要件

Installation

インストール

macOS

macOS

Download the .pkg installer and run it. The installer will:

.pkg インストーラをダウンロードして実行してください。インストーラは以下を行います：

1. Install the application to /Applications/TinyChannels Edge.app
2. Create the data directory at /Library/Application Support/TinyChannels Edge/
3. Install and load the LaunchDaemon

1. アプリケーションを /Applications/TinyChannels Edge.app にインストール
2. データディレクトリを /Library/Application Support/TinyChannels Edge/ に作成
3. LaunchDaemon をインストールして起動

Windows

Windows

Run the .msi installer. Binaries are installed to C:\Program Files\TinyChannels Edge\ and configuration is stored in C:\ProgramData\TinyChannels Edge\.

.msi インストーラを実行してください。バイナリは C:\Program Files\TinyChannels Edge\ に、設定は C:\ProgramData\TinyChannels Edge\ に保存されます。

Linux (Debian/Ubuntu)

Linux (Debian/Ubuntu)

sudo dpkg -i tinychannels-edge_1.0.3_amd64.deb
# or for arm64
sudo dpkg -i tinychannels-edge_1.0.3_arm64.deb

Linux (RHEL/CentOS)

Linux (RHEL/CentOS)

sudo rpm -i tinychannels-edge-1.0.3-1.x86_64.rpm
# or for aarch64
sudo rpm -i tinychannels-edge-1.0.3-1.aarch64.rpm

On the first run of the CLI utility, you will be prompted to review and accept the End User License Agreement.

CLI ユーティリティを初めて実行するときに、使用許諾契約書の確認と承認を求められます。

Configuration File

設定ファイル

The configuration file tinychannels-edge.yaml is located in the application data directory:

設定ファイル tinychannels-edge.yaml はアプリケーションデータディレクトリにあります：

Default Configuration

デフォルト設定

Directory:
  HomeDirectory: /Library/Application Support/TinyChannels Edge

LogRotation:
  Generations: 4

Registration

登録

Before the Edge can relay traffic, it must be registered with an Authorization Manager (TinyChannels Center).

Edge がトラフィックをリレーする前に、認可マネージャー（TinyChannels Center）に登録する必要があります。

Using the Utility (macOS / Windows)

ユーティリティを使用（macOS / Windows）

1. Open TinyChannels Edge Utility
2. In the Register Edge section, enter:
   • Edge Name — a friendly name for this Edge
   • Authorization Manager Endpoint — e.g. https://your-center-host
   • Edge Address / Hostname — the address Ends will use to connect
   • Edge Port — the externally reachable UDP port (default: 4433)
   • Protection Code — a shared code provided by the Authorization Manager operator (rotates weekly, viewable in the Portal)
3. Click Register
4. If the server presents an untrusted TLS certificate, review and accept it in the dialog
5. After successful registration, start the daemon

1. TinyChannels Edge ユーティリティを開く
2. Edge を登録セクションで以下を入力：
   • Edge 名 — この Edge の表示名
   • 認可マネージャーエンドポイント — 例: https://your-center-host
   • Edge アドレス / ホスト名 — エンドが接続に使用するアドレス
   • Edge ポート — 外部から到達可能な UDP ポート（デフォルト: 4433）
   • 保護コード — 認可マネージャー運用者から提供される共有コード（毎週ローテーションされ、Portal で確認可能）
3. 登録をクリック
4. サーバーが信頼されていない TLS 証明書を提示した場合、ダイアログで確認して受け入れる
5. 登録成功後、デーモンを起動

After registration, the address/port and the internal listening port can be edited from the Utility (the address/port require restarting the daemon to take effect). The address/port change is also synchronized to the Authorization Manager.

登録後、アドレス／ポートおよび内部リスニングポートはユーティリティから編集できます（アドレス／ポート変更はデーモンを再起動する必要があります）。アドレス／ポートの変更は認可マネージャーにも同期されます。

Using the CLI (Linux)

CLI を使用（Linux）

sudo tinychannels-edge-utility init \
  --auth-manager-endpoint https://your-center-host \
  --edge-address your-edge-host \
  --edge-port 4433
# --edge-name defaults to the system hostname (override with --edge-name)
# Protection code is prompted interactively (input is hidden)

You will be prompted to enter the protection code (input is hidden). If the server certificate is untrusted, you will also be prompted to review and accept it in the terminal.

保護コードの入力を求められます（入力は表示されません）。サーバー証明書が信頼されていない場合は、ターミナルで証明書の確認・承認も求められます。

TLS Certificate

TLS 証明書

During registration, the Edge verifies the Authorization Manager's TLS server certificate. If the certificate is not trusted by the system (e.g. self-signed), the Edge will prompt you to review and accept it.

登録時に、Edge は認可マネージャーの TLS サーバー証明書を検証します。証明書がシステムに信頼されていない場合（自己署名証明書など）、確認と承認を求められます。

The accepted certificate is stored in registration.json and used for all subsequent connections (certificate pinning).

承認された証明書は registration.json に保存され、以後のすべての接続で使用されます（証明書ピンニング）。

Utility Overview

ユーティリティ概要

The TinyChannels Edge Utility provides a graphical interface for managing the Edge on macOS and Windows. It displays:

TinyChannels Edge ユーティリティは、macOS および Windows で Edge を管理するグラフィカルインターフェースを提供します。以下が表示されます：

• Registration Status — whether the Edge is registered, UUID, Authorization Manager endpoint, certificate validity, and editable Address/Port (the externally reachable endpoint)
• Daemon Management — start/stop the Edge daemon, view status and active sessions, and edit the internal Listening Port
• Version Information — application version, Rust compiler version, software licenses

• 登録ステータス — Edge の登録状態、UUID、認可マネージャーエンドポイント、証明書有効期間、編集可能なアドレス／ポート（外部から到達可能なエンドポイント）
• デーモン管理 — Edge デーモンの起動／停止、ステータスとアクティブセッションの確認、内部リスニングポートの編集
• バージョン情報 — アプリバージョン、Rust コンパイラバージョン、ソフトウェアライセンス

Daemon Management

デーモン管理

macOS

macOS

The daemon runs as a LaunchDaemon (com.shimousa.tinychannels.edge). You can manage it via the Utility or manually:

デーモンは LaunchDaemon（com.shimousa.tinychannels.edge）として動作します。ユーティリティまたは手動で管理できます：

# Start
sudo launchctl load /Library/LaunchDaemons/com.shimousa.tinychannels.edge.plist

# Stop
sudo launchctl unload /Library/LaunchDaemons/com.shimousa.tinychannels.edge.plist

Windows

Windows

The daemon runs as a Windows Service (TinyChannelsEdgeService, displayed as "TinyChannels Edge Service"). Manage via the Utility or:

デーモンは Windows サービス（TinyChannelsEdgeService、表示名は「TinyChannels Edge Service」）として動作します。ユーティリティまたは以下で管理：

sc start TinyChannelsEdgeService
sc stop TinyChannelsEdgeService

Linux

Linux

sudo systemctl start tinychannels-edge
sudo systemctl stop tinychannels-edge
sudo systemctl status tinychannels-edge

CLI Reference

CLI リファレンス

Registration (Linux CLI)

登録（Linux CLI）

sudo tinychannels-edge-utility init \
  --auth-manager-endpoint <URL> \
  --edge-address <ADDRESS> \
  --edge-port <PORT> \
  [--edge-name <NAME>]

The protection code is requested via an interactive prompt with hidden input, not as a CLI flag. Untrusted server certificates are reviewed and accepted in the same terminal session.

保護コードは CLI フラグではなく、入力非表示の対話プロンプトで尋ねられます。信頼されていないサーバー証明書も同じターミナルセッションで確認・承認します。

Other CLI Subcommands

その他の CLI サブコマンド

tinychannels-edge-utility status   # Show registration and daemon status
tinychannels-edge-utility start    # Start the daemon
tinychannels-edge-utility stop     # Stop the daemon
tinychannels-edge-utility serve --port 9090   # Start the headless web UI server

Edge Binary Version

Edge バイナリバージョン

tinychannels-edge version

Troubleshooting

トラブルシューティング

Registration Fails

登録に失敗する

• Verify the Authorization Manager endpoint URL is correct (no /api suffix needed)
• Check network connectivity to the Authorization Manager
• If using a self-signed certificate, ensure you accept the certificate when prompted
• 401 Unauthorized — the protection code is missing or wrong. Get the current code from the Portal (Edge/End page) and try again. The code rotates weekly.
• 409 Conflict — only one Edge is allowed in this version. Revoke the existing Edge in the Portal before re-registering.

• 認可マネージャーのエンドポイント URL が正しいことを確認（/api サフィックスは不要）
• 認可マネージャーへのネットワーク接続を確認
• 自己署名証明書を使用している場合、プロンプトで証明書を承認すること
• 401 Unauthorized — 保護コードが未指定または誤りです。Portal（Edge/End ページ）から現在のコードを取得して再試行してください。コードは毎週ローテーションされます。
• 409 Conflict — このバージョンでは Edge は 1 つしか登録できません。再登録する前に Portal で既存の Edge を取り消してください。

Daemon Won't Start

デーモンが起動しない

• Ensure the Edge is registered first
• Check that UDP port 4433 is not in use by another process
• Review logs in the logs/ directory under the data folder

• Edge が先に登録されていることを確認
• UDP ポート 4433 が他のプロセスで使用されていないことを確認
• データフォルダ内の logs/ ディレクトリのログを確認

Decryption Failed (Wrong Machine)

復号化に失敗（別のマシン）

The private key is encrypted with a machine-specific key. If you see "AES-256-GCM decryption failed", the registration.json file was likely copied from another machine. Re-register the Edge on this machine.

秘密鍵はマシン固有の鍵で暗号化されています。「AES-256-GCM decryption failed」が表示された場合、registration.json ファイルが別のマシンからコピーされた可能性があります。このマシンで Edge を再登録してください。

Log Locations

ログの場所