Programming Field

stream-connector

stream-connector は、ソケット通信やパイプ入出力を接続・転送する Windows アプリケーションです。

※ プログラム内のテキストおよびパッケージ内の説明ファイルは英語で記述しています。本ページに日本語の説明を記載しています。

ダウンロード

配布は GitHub で行っています。stream-connector プロジェクトの「Releases」から最新バージョンをダウンロードしてください。

※ Windows 10 でのみ動作確認を行っています。また、64ビット版Windowsでは x64 版の利用を推奨します。

使い方

コマンドラインから後述するオプションを利用し、「listener」と「connector」を指定して起動します。起動するとタスクバーにアイコンが追加され、このアイコンをダブルクリックすることでステータスウィンドウが表示されます。

オプション

--listener (-l) および --connector (-c) は必須オプションです。これらが指定されていない場合は Usage ダイアログが表示されます。

Usage: stream-connector.exe <options>

<options>:
  -h, -?, --help : Show this help
  -l <listener>, --listener <listener> : [Required] Add listener (can be specified more than one)
  -c <connector>, --connector <connector> : [Required] Set connector
  -n <name>, --name <name> : User-defined name
  --log <level> : Set log level
    <level>: error, info, debug (default: error)
  --wsl-socat-log-level <level> : Set log level for WSL socat
    <level>: 0 (nothing), 1 (-d), 2 (-dd), 3 (-ddd), 4 (-dddd) (default: 0)
  --wsl-timeout <millisec> : Set timeout for WSL preparing (default: 30000)

<listener>:
  tcp-socket [-4 | -6] [<address>:]<port> : TCP socket listener (port num. can be 0 for auto-assign)
    alias for 'tcp-socket': s, sock, socket, tcp
  unix-socket [--abstract] <file-path> : Unix socket listener (listener with the socket file)
    alias for 'unix-socket': u, unix
  cygwin-sockfile <win-file-path> : Listener with Cygwin-spec socket file
    alias for 'cygwin-sockfile': c
  pipe <pipe-name> : Named-pipe listener
    alias for 'pipe': p
  wsl-tcp-socket [-d <distribution>] [-4 | -6] [<address>:]<port> : TCP socket listener in WSL (port num. can be 0 for auto-assign)
    alias for 'wsl-tcp-socket': ws, wt
  wsl-unix-socket [-d <distribution>] <wsl-file-path> : Unix socket listener in WSL (listener with the socket file in WSL)
    alias for 'wsl-unix-socket': wu

<connector>:
  tcp-socket <address>:<port> : TCP socket connector (port num. cannot be 0)
  unix-socket [--abstract] <file-name> : Unix socket connector
  pipe <pipe-name> : Named-pipe connector
  wsl-tcp-socket [-d <distribution>] <address>:<port> : TCP socket connector in WSL (port num. cannot be 0)
  wsl-unix-socket [-d <distribution>] [--abstract] <wsl-file-path> : Unix socket connector in WSL

-h, -?, --help

Usage ダイアログを表示します。

-l <listener>, --listener <listener>

(必須オプション)

データ転送元となる「listener」を指定します(複数指定することができます)。「listener」はプログラム起動時に初期化され接続を待機します。

<listener> には以下を指定することができます。

tcp-socket [-4 | -6] [<address>:]<port>

tcp-socket のエイリアス: s , sock , socket , tcp

指定のアドレス・ポート番号を利用してTCPソケットを作成し接続を待機します。

  • -4 が指定されている場合は IPv4 を利用します。
  • -6 が指定されている場合は IPv6 を利用します。
  • -4 も -6 も指定されていない場合は、アドレスが [ で始まる場合は IPv6 を、それ以外の場合は IPv4 を利用します。

<address> が省略された場合は、127.0.0.1 または [::1] を利用します(※ any address ではないのでご注意ください)。

unix-socket [--abstract] <file-name>

unix-socket のエイリアス: u , unix

指定したファイル名を利用してUnixソケットを作成し接続を待機します。--abstract (または -a) が指定されている場合は「abstract」ソケットとして作成します。

ファイル名に該当するファイルは書き込み可能であり、また存在しないファイルである必要があります。このファイルはプログラム起動時に作成されますが、終了時に自動で削除されます。

※ Unixソケットは一部のWindows 10のバージョンではうまく動作しません。(ビルド 19042 以降では動作します。)

cygwin-sockfile <file-name>

cygwin-sockfile のエイリアス: c

指定したファイル名を利用してCygwinベースのUnixソケットを作成し接続を待機します。通常のUnixソケットと異なり、CygwinまたはMSYS2と同じ方法でファイルが作成されます(Cygwin/MSYS2環境で作成されたプログラムから接続できます)。このファイルはプログラム起動時に作成されますが、終了時に自動で削除されます。

※ このオプションの利用時にCygwin/MSYS2環境は必要ありません。

pipe <pipe-name>

pipe のエイリアス: p

指定したパイプ名を利用してWindowsパイプを作成し接続を待機します。パイプ名(<pipe-name>)は \\.\pipe\ で始まる名前である必要があります。

wsl-tcp-socket [--distribution <distro>] [-4 | -6] [<address>:]<port>

wsl-tcp-socket のエイリアス: ws , wt

x86 版プログラムでは利用できません。

WSL環境に指定のアドレス・ポート番号を利用してTCPソケットを作成し接続を待機します。

指定したWSL環境に socat がインストールされている必要があります。(当然ながら、WindowsでWSLが利用可能になっている必要があります。)

  • --distribution <distro> (または -d <distro>) には、接続を待機したい(インストール済みの)WSLディストリビューションを指定します。
  • --distribution (または -d) の指定がない場合は、既定のWSLディストリビューションを利用します。
  • -4 が指定されている場合は IPv4 を利用します。
  • -6 が指定されている場合は IPv6 を利用します。
  • -4 も -6 も指定されていない場合は、アドレスが [ で始まる場合は IPv6 を、それ以外の場合は IPv4 を利用します。

<address> が省略された場合は、127.0.0.1 または [::1] を利用します(※ any address ではないのでご注意ください)。

wsl-unix-socket [--distribution <distro>] <wsl-file-name>

wsl-unix-socket のエイリアス: wu

WSL環境に指定したファイル名を利用してUnixソケットを作成し接続を待機します。

指定したWSL環境に socat がインストールされている必要があります。(当然ながら、WindowsでWSLが利用可能になっている必要があります。)

  • --distribution <distro> (または -d <distro>) には、接続を待機したい(インストール済みの)WSLディストリビューションを指定します。
  • --distribution (または -d) の指定がない場合は、既定のWSLディストリビューションを利用します。
  • ファイル名(<wsl-file-name>)は対象のWSL環境で有効なファイルパスである必要があります(ルートディレクトリが / となるパス名です)。このファイルはプログラム起動時に作成されますが、終了時に自動で削除されます。

-c <connector>, --connector <connector>

(必須オプション)

データの転送先となる「connector」を指定します。「connector」はどれかの「listener」に接続があった際に作成されます(プログラム開始時点では作成されません)。

<connector> に指定できるオプションは以下の通りです。

tcp-socket <address>:<port>

tcp-socket のエイリアス: s , sock , socket , tcp

指定のアドレス・ポート番号に接続するTCPソケットを作成し通信します。

unix-socket [--abstract] <file-name>

unix-socket のエイリアス: u , unix

指定のUnixソケットファイルに接続するUnixソケットを作成し通信します。--abstract (または -a) が指定されている場合は「abstract」ソケットとして作成します。

ファイル名に該当するファイルは「Unixソケット」扱いのファイル(リパースポイント)としてアクセス可能である必要があります。

※ Unixソケットは一部のWindows 10のバージョンではうまく動作しません。(ビルド 19042 以降では動作します。)

pipe <pipe-name>

pipe のエイリアス: p

指定したパイプ名を利用してWindowsパイプをオープンし通信します。パイプ名(<pipe-name>)は \\.\pipe\ で始まる存在するパイプ名である必要があります。

wsl-tcp-socket [--distribution <distro>] <address>:<port>

wsl-tcp-socket のエイリアス: ws , wt

x86 版プログラムでは利用できません。

WSL環境における指定のアドレス・ポート番号に接続するTCPソケットを作成し通信します。

指定したWSL環境に socat がインストールされている必要があります。(当然ながら、WindowsでWSLが利用可能になっている必要があります。)

  • --distribution <distro> (または -d <distro>) には、接続を待機したい(インストール済みの)WSLディストリビューションを指定します。
  • --distribution (または -d) の指定がない場合は、既定のWSLディストリビューションを利用します。
wsl-unix-socket [--distribution <distro>] <wsl-file-name>

wsl-unix-socket のエイリアス: wu

WSL環境に存在する指定のUnixソケットファイルに接続するUnixソケットを作成し通信します。

指定したWSL環境に socat がインストールされている必要があります。(当然ながら、WindowsでWSLが利用可能になっている必要があります。)

  • --distribution <distro> (または -d <distro>) には、接続を待機したい(インストール済みの)WSLディストリビューションを指定します。
  • --distribution (または -d) の指定がない場合は、既定のWSLディストリビューションを利用します。
  • ファイル名(<wsl-file-name>)は対象のWSL環境で有効なファイルパスである必要があります(ルートディレクトリが / となるパス名です)。このファイルはプログラム起動時に作成されますが、終了時に自動で削除されます。

-n <name>, --name <name>

任意の名前を指定します。この名前はタスクバーアイコンのアイコン名やウィンドウのタイトル名に利用されるため、複数の stream-connector プログラムを実行する場合の区別用の名前として利用することができます。

--log <level>

ステータスウィンドウ上のログの詳細度を指定します。<level> には error (既定値; エラーのみ出力)、info (やや詳細に出力)、debug (より詳細に出力) が指定できます。

--wsl-timeout <millisec>

WSL上での処理に必要な準備処理のタイムアウト時間をミリ秒で指定します。(既定値: 30000 (30秒))

--wsl-socat-log-level <level>

WSL上で実行する socat のログ詳細度を指定します。<level> には以下の数値を指定します。

  • 0 : 既定のログレベル (既定値)
  • 1 : -d 相当
  • 2 : -dd 相当
  • 3 : -ddd 相当
  • 4 : -dddd 相当

※ 1～4の代わりに -d -dd -ddd -dddd も指定できます。

-x <proxy-id>, --proxy <proxy-id>

内部で使用されます。

使用例

stream-connector -l tcp-socket 127.0.0.1:3001 -c tcp-socket my-host.mydomain:3001

ポート3001番(アドレス: 127.0.0.1)を利用して接続を待機(リッスン)し、接続を受けたらデータを my-host.mydomain:3001 に相互(in-out)に転送します。

※ これは「ポートフォワーディング」となりますが、より単純なポートフォワーディングは netsh interface portproxy コマンドを利用するのが適しています。

stream-connector -l wsl-tcp-socket 6000 -c tcp-socket localhost:6000

WSL環境(既定のディストリビューション)でポート6000番に対するリッスンを行い、接続を受けたらデータを localhost:6000 に相互に転送します。

stream-connector -l cygwin-sockfile C:\Temp\my-agent.sock -l wsl-unix-socket -d Ubuntu-20.04 /tmp/my-agent.sock -c pipe \\.\pipe\openssh-ssh-agent

my-agent.sock というファイルを C:\Temp とWSL環境の /tmp にそれぞれ(前者は Cygwin ソケットファイルとして、後者はUnixソケットファイルとして)作成し、それぞれ接続を受けたらデータをパイプ \\.\pipe\openssh-ssh-agent に相互に転送します。この指定を利用すると、SSHエージェント処理をCygwin/MSYS2ベースのSSHプログラムおよびWSL内のSSHプログラムから、Windows OpenSSHのSSHエージェントに転送することができます。