VS Code SSH Config 設定ガイド：リモート開発を快適に

By /

VS Code SSH Config 設定ガイド：リモート開発を極めるための完全マニュアル

はじめに：リモート開発の可能性とSSH Configの重要性

現代の開発ワークフローにおいて、リモート環境での開発はもはや特別なことではありません。クラウド上の仮想マシン、オンプレミスのサーバー、WSL (Windows Subsystem for Linux) 環境など、ローカルマシン以外の環境でコードを実行・デバッグする機会は増えています。これにより、開発環境の統一、高性能なサーバーリソースの活用、複数人での環境共有などが容易になります。

Visual Studio Code (VS Code) は、その強力なリモート開発機能により、このワークフローを劇的に快適にしてくれます。特に、VS Codeの「Remote – SSH」拡張機能を利用することで、ローカルにあるVS Codeの使い慣れたインターフェースをそのままに、リモートサーバー上のファイル編集、ターミナル操作、デバッグなどを行うことができます。

Remote – SSH拡張機能がリモートサーバーに接続する際に使用するのが、SSH (Secure Shell) プロトコルです。そして、SSH接続をより効率的、かつ柔軟に行うために不可欠なのが、SSH Configファイルです。

SSH Configファイルに接続情報を定義しておくことで、毎回リモートサーバーのIPアドレス、ユーザー名、ポート番号、認証方法などを手動で入力する手間を省くことができます。さらに、単なるショートカット機能に留まらず、認証鍵の指定、ジャンプホスト経由の接続、接続の多重化による高速化、ポートフォワーディングなど、様々な高度な設定を記述することが可能です。

このガイドでは、VS Codeでのリモート開発を快適にするためのSSH Configの設定方法について、基本的なことから応用的なテクニックまで、詳細かつ網羅的に解説します。SSH Configを使いこなすことで、リモート開発の効率性と快適性を格段に向上させることができるでしょう。

第1章：SSH Configとは？ 基本を理解する

SSH Configは、SSHクライアントの接続設定を記述するためのテキストファイルです。デフォルトでは、ユーザーのホームディレクトリにある .ssh ディレクトリ内に config という名前で保存されています。

  • Linux/macOS: ~/.ssh/config
  • Windows: %USERPROFILE%\.ssh\config (または、Git BashやWSLを使っている場合は ~/.ssh/config)

このファイルにリモートホストごとの接続設定を記述しておくことで、SSHコマンドを実行する際に、例えば ssh my-server のように、短いエイリアス名だけで接続できるようになります。VS CodeのRemote – SSH拡張機能も、このSSH Configファイルを読み込んでリモートホストへの接続を行います。

1.1 SSH Configファイルの基本構造

SSH Configファイルは、一つまたは複数の「ホストエントリ」で構成されます。各ホストエントリは、Host キーワードで始まり、その後にそのエントリに名前（エイリアス）を付けます。そして、その Host エントリに対する各種設定を、インデント（通常はスペース）を使って記述します。

基本的な構造は以下のようになります。

“`sshconfig

これはコメント行です

Host ホスト名エイリアス
Hostname 実際のホスト名またはIPアドレス
User 接続ユーザー名
Port ポート番号

Host 別のホストエイリアス
Hostname 別の実際のホスト名
User 別の接続ユーザー名
IdentityFile 秘密鍵ファイルのパス
# その他の設定…
“`

# で始まる行はコメントとして扱われ、設定には影響しません。

1.2 SSH Configの主な基本設定項目

VS Codeでのリモート開発に最低限必要な基本的な設定項目を説明します。

  • Host:

    • この設定エントリの名前、つまりエイリアスを指定します。VS CodeやSSHコマンドからこの名前を使って接続します。
    • ワイルドカード (*, ?) を使用することも可能ですが、具体的なホスト名のエントリよりも後に記述しないと、意図しない設定が適用される可能性があります。
    • 例: Host my-remote-server

  • Hostname:

    • 接続先の実際のホスト名またはIPアドレスを指定します。
    • 例: Hostname 192.168.1.100 または Hostname example.com

  • User:

    • 接続に使用するリモートユーザー名を指定します。
    • これを指定しない場合、ローカルマシンのユーザー名がデフォルトで使用されます。
    • 例: User ubuntu

  • Port:

    • 接続に使用するリモートSSHポート番号を指定します。デフォルトは22です。
    • SSHサーバーが標準以外のポートを使用している場合に指定します。
    • 例: Port 2222

1.3 簡単なSSH Configの例

例えば、以下の情報をを持つサーバーに接続したいとします。

  • IPアドレス: 192.168.1.100
  • ユーザー名: myuser
  • SSHポート: 22 (デフォルト)

この場合、SSH Configファイル (~/.ssh/config) には以下のように記述します。

sshconfig
Host my-server
Hostname 192.168.1.100
User myuser
# Port 22 # ポートが22の場合は省略可能

これで、VS CodeのRemote – SSH拡張機能から「my-server」という名前でこのサーバーに接続できるようになります。また、ターミナルからも ssh my-server コマンドで接続できます。

別の例として、IPアドレス 10.0.0.5、ユーザー名 admin、ポート 2222 のサーバーに接続する場合です。

sshconfig
Host admin-server
Hostname 10.0.0.5
User admin
Port 2222

これらの基本設定だけでも、毎回IPアドレスなどを入力する手間が省け、VS Codeからの接続が非常にスムーズになります。

第2章：VS Code Remote – SSH拡張機能のセットアップ

SSH Configを利用してVS Codeからリモート開発を行うには、まずVS Codeに「Remote – SSH」拡張機能をインストールする必要があります。

  1. VS Codeを開きます。
  2. アクティビティバー（左側のアイコンが並んだバー）から「拡張機能」アイコン（四角が3つと1つ離れたアイコン）をクリックします。
  3. 検索バーに「Remote – SSH」と入力し、Microsoftが提供する公式の拡張機能を見つけます。
  4. 「インストール」ボタンをクリックしてインストールします。

インストールが完了すると、VS Codeの左下隅に緑色のリモートインジケーターが表示されます。このアイコンをクリックすることで、リモート接続に関する様々な操作を行うことができます。

2.1 VS CodeからSSH Configを読み込む

Remote – SSH拡張機能は、デフォルトでユーザーの ~/.ssh/config ファイルを自動的に読み込みます。インストール後、VS Codeの左下のリモートインジケーターをクリックすると、上部にコマンドパレットが表示されます。ここで「Connect to Host…」を選択すると、SSH Configファイルに記述されている Host エントリのリストが表示されるはずです。

もしリストに何も表示されない場合や、別のSSH Configファイルを読み込ませたい場合は、VS Codeの設定で remote.SSH.configFile のパスを指定することで変更できます。

  1. VS Codeの「ファイル」>「ユーザー設定」>「設定」（または Ctrl+,）を開きます。
  2. 検索バーに remote.SSH.configFile と入力します。
  3. 設定項目が表示されるので、SSH Configファイルのフルパスを指定します。デフォルトは空欄で、この場合は標準のパス (~/.ssh/config) が使用されます。

2.2 VS Codeからの接続手順

SSH Configにホスト情報を設定し、Remote – SSH拡張機能がそれを読み込んでいることを確認したら、以下の手順で接続します。

  1. VS Codeの左下隅にある緑色のリモートインジケーターをクリックします。
  2. コマンドパレットが表示されるので、「Connect to Host…」を選択します。
  3. SSH Configファイルに定義されているホスト名のリストが表示されるので、接続したいホスト名を選択します。
  4. 初めて接続する場合や、SSHキーのパスフレーズが設定されている場合などは、パスワードやパスフレーズの入力を求められることがあります。指示に従って入力します。
  5. 接続が成功すると、VS Codeのウィンドウが新しいウィンドウとして開き、左下のリモートインジケーターが「SSH: ホスト名」のように表示されます。これでリモートサーバーに接続した状態でVS Codeを使用できます。ファイルエクスプローラーにはリモートサーバーのファイルシステムが表示され、ターミナルを開けばリモートサーバーのシェルが起動します。

第3章：SSH Configの応用：VS Codeリモート開発をさらに快適に

ここからは、VS Codeでのリモート開発の利便性、セキュリティ、パフォーマンスを向上させるための、より応用的なSSH Configの設定項目を解説します。

3.1 認証方法の設定：パスワード vs 公開鍵

SSHの認証方法にはいくつかありますが、セキュリティと自動化の観点から、公開鍵認証が強く推奨されます。パスワード認証は、パスワードが盗聴されるリスクや、ブルートフォース攻撃に弱いといった欠点があります。

3.1.1 パスワード認証

SSH Configでパスワード認証を指定する設定項目はありません。デフォルトでは、公開鍵認証が失敗した場合にパスワード認証が試みられます。しかし、セキュリティ上の理由から、リモートサーバー側でパスワード認証を無効化している場合が多いです。

VS Codeからパスワード認証で接続する場合、接続時にパスワードの入力を求められます。セキュリティのため、可能な限り公開鍵認証に移行することを強く推奨します。

3.1.2 公開鍵認証 (最も推奨)

公開鍵認証では、ローカルマシンに「秘密鍵」、リモートサーバーに「公開鍵」を配置します。接続時には、秘密鍵の所有者であることを証明することで認証を行います。

ステップ1：SSHキーペアの生成

ローカルマシンでSSHキーペアを生成します。既に持っている場合はこのステップはスキップできます。

bash
ssh-keygen -t rsa -b 4096 -C "[email protected]"

  • -t rsa: キーのタイプをRSAに指定します。他のタイプ（ed25519など）も利用可能です。
  • -b 4096: RSAキーのビット長を4096bitに指定します（デフォルトは2048bit）。長いほど安全ですが、処理負荷は若干増えます。
  • -C "[email protected]": 公開鍵ファイルにコメントを追加します。誰の鍵か分かりやすくするためにメールアドレスなどを指定することが多いです。

コマンドを実行すると、キーペアの保存場所とパスフレーズの設定を求められます。

Enter file in which to save the key (/home/youruser/.ssh/id_rsa): # Enterでデフォルトを使用
Enter passphrase (empty for no passphrase): # ここでパスフレーズを入力（またはEnterでスキップ）
Enter same passphrase again: # パスフレーズを再入力

パスフレーズは、秘密鍵を保護するためのパスワードです。設定しておくと、秘密鍵が盗まれてもパスフレーズを知らなければ悪用されません。しかし、接続のたびにパスフレーズの入力が必要になります。後述するSSHエージェントを利用することで、パスフレーズの入力を省略しつつセキュリティを維持できます。

生成されるファイルは以下の2つです。

  • ~/.ssh/id_rsa (または指定した名前): 秘密鍵ファイル。厳重に管理し、誰にも教えないでください。
  • ~/.ssh/id_rsa.pub (または指定した名前に.pubが付いたファイル): 公開鍵ファイル。これはリモートサーバーにコピーします。

ステップ2：公開鍵のリモートサーバーへの設置

生成した公開鍵 (id_rsa.pub) の内容を、接続したいリモートサーバーの接続ユーザーのホームディレクトリにある .ssh/authorized_keys ファイルに追加します。

最も簡単な方法は ssh-copy-id コマンドを使うことです。

bash
ssh-copy-id -i ~/.ssh/id_rsa.pub myuser@remote-server-hostname-or-ip

このコマンドは、指定した秘密鍵 (-i) に対応する公開鍵を、指定したリモートサーバーの指定ユーザー (myuser@...) の ~/.ssh/authorized_keys ファイルに自動的に追記してくれます。初回実行時にはパスワード認証が必要になります。

ssh-copy-id コマンドが利用できない場合は、手動で公開鍵の内容をコピー＆ペーストする必要があります。

  1. ローカルマシンで公開鍵の内容を表示します。
    bash
    cat ~/.ssh/id_rsa.pub
  2. 表示された公開鍵の内容（ssh-rsa ... [email protected] のような文字列）を全てコピーします。
  3. リモートサーバーにパスワード認証などで接続します。
  4. リモートサーバーで ~/.ssh ディレクトリが存在しない場合は作成します。
    bash
    mkdir -p ~/.ssh
    chmod 700 ~/.ssh
  5. .ssh/authorized_keys ファイルが存在しない場合は作成し、存在する場は編集モードで開きます。
    bash
    nano ~/.ssh/authorized_keys # または vim など好きなエディタで
  6. ファイル末尾に、コピーした公開鍵の内容を新しい行として貼り付けます。
  7. ファイルを保存して閉じます。
  8. authorized_keys ファイルのパーミッションが正しいことを確認します。
    bash
    chmod 600 ~/.ssh/authorized_keys

これで公開鍵認証の準備が整いました。

ステップ3：SSH Configでの公開鍵指定

SSH Configファイルで、どの秘密鍵を使って接続するかを指定します。

sshconfig
Host my-server
Hostname 192.168.1.100
User myuser
IdentityFile ~/.ssh/id_rsa # 使用する秘密鍵ファイルのパスを指定

  • IdentityFile: 接続に使用する秘密鍵ファイルのフルパスを指定します。デフォルトでは ~/.ssh/id_rsa, ~/.ssh/id_dsa, ~/.ssh/id_ecdsa, ~/.ssh/id_ed25519 など標準的な名前の秘密鍵を自動的に探して試行しますが、複数の秘密鍵を使い分けている場合は明示的に指定するのが確実です。

  • IdentitiesOnly yes: 複数の秘密鍵ファイルを所有している場合で、IdentityFile で指定した秘密鍵「のみ」を使って認証を試みたい場合に指定します。これを yes に設定することで、SSHクライアントが他のデフォルト秘密鍵やSSHエージェントに登録されている鍵を試行することを防ぎ、認証試行回数の上限を超えて接続が拒否されるのを避けることができます。

    sshconfig
    Host my-server
    Hostname 192.168.1.100
    User myuser
    IdentityFile ~/.ssh/my_custom_key
    IdentitiesOnly yes # この秘密鍵だけを使用する

3.1.3 SSHエージェントの活用

パスフレーズ付きの秘密鍵を使用している場合、接続のたびにパスフレーズを入力する必要があります。これを回避しつつセキュリティを維持するのがSSHエージェント (ssh-agent) です。

SSHエージェントは、起動中に秘密鍵をメモリ上で管理し、認証要求に対してパスフレーズなしで応答するプログラムです。パスフレーズの入力は、エージェントに秘密鍵を登録する最初の1回だけになります。

  • ssh-agent: SSHエージェントを起動するコマンド。通常はログイン時に自動的に起動されるよう設定されています。
  • ssh-add: 秘密鍵をSSHエージェントに登録するコマンド。
    bash
    ssh-add ~/.ssh/id_rsa
    # パスフレーズを求められるので入力
    これで、エージェントが起動している間は、この秘密鍵を使った接続時にパスフレーズの入力が不要になります。

  • AddKeysToAgent yes: SSH Configでこのオプションを yes に設定すると、その秘密鍵を使って認証に成功した際に、自動的にその秘密鍵をSSHエージェントに登録します。VS Codeから接続する場合に便利です。

    sshconfig
    Host my-server
    Hostname 192.168.1.100
    User myuser
    IdentityFile ~/.ssh/id_rsa
    AddKeysToAgent yes # 初回接続時にエージェントに鍵を登録する

  • IdentityAgent: 使用するSSHエージェントを指定します。通常はデフォルトのソケットパスで問題ありませんが、カスタムのエージェントを使用する場合などに指定します。SSH_AUTH_SOCK 環境変数に指定されたパスを使用する場合は IdentityAgent $SSH_AUTH_SOCK と指定します。

公開鍵認証とSSHエージェントを組み合わせることで、安全かつスムーズなリモート接続を実現できます。

3.2 プロキシ接続：ジャンプホスト経由

ネットワーク環境によっては、目的のリモートサーバーに直接SSH接続できない場合があります。このような場合、一度別のサーバー（ジャンプホストまたは踏み台サーバー）を経由して接続する必要があります。SSH Configでは、これを簡単に設定できます。

3.2.1 ProxyJump を使用する方法 (推奨)

ProxyJump は、SSHクライアントの新しいバージョン（OpenSSH 7.3以降）で導入された、ジャンプホスト経由の接続をシンプルに設定するための方法です。

“`sshconfig
Host jump-host
Hostname 192.168.1.200
User jumpuser

Host target-server
Hostname 10.0.0.100
User targetuser
ProxyJump jump-host # ジャンプホストのHost名を指定
“`

この設定により、ssh target-server または VS Codeから「target-server」に接続しようとすると、自動的にまず jump-host に接続し、そこから target-server に接続するようになります。

複数のジャンプホストを経由する場合も、カンマ区切りで指定できます。

“`sshconfig
Host jump-host1
Hostname 192.168.1.200
User jumpuser1

Host jump-host2
Hostname 192.168.2.200
User jumpuser2
ProxyJump jump-host1 # jump-host1を経由してjump-host2へ

Host target-server
Hostname 10.0.0.100
User targetuser
ProxyJump jump-host2 # jump-host2を経由してtarget-serverへ (結果的にjump-host1 -> jump-host2 -> target-server)

または、ProxyJump jump-host1,jump-host2 とまとめて書くことも可能

“`

ProxyJump の引数には、SSH Configに定義された Host 名だけでなく、user@hostname:port の形式で直接指定することも可能です。

sshconfig
Host target-server
Hostname 10.0.0.100
User targetuser
ProxyJump [email protected]:22 # user@hostname:port 形式で指定

3.2.2 ProxyCommand を使用する方法 (より汎用的)

ProxyCommand は、SSHクライアントがリモートサーバーへの接続を確立する際に実行する外部コマンドを指定する設定です。ProxyJump は内部的に ProxyCommand を使用していますが、ProxyCommand を直接使うことで、より複雑なプロキシ設定（例: netcat や socat を使う、認証プロキシを経由するなど）も可能です。

基本的なジャンプホスト経由の接続を ProxyCommand で記述すると以下のようになります。

“`sshconfig
Host jump-host
Hostname 192.168.1.200
User jumpuser

Host target-server
Hostname 10.0.0.100
User targetuser
ProxyCommand ssh -W %h:%p jump-host # %hはターゲットホスト名、%pはターゲットポート番号
“`

  • ProxyCommand ssh -W %h:%p jump-host: これは、「ssh jump-host を実行し、そのSSH接続上で標準入出力を介して (-W) ターゲットホスト %h のターゲットポート %p に接続せよ」という意味になります。

ProxyCommand は非常に強力で柔軟な設定ですが、外部コマンドの実行に依存するため、環境によっては利用できない場合や、コマンドのパスを指定する必要がある場合など注意が必要です。特に理由がなければ、シンプルで新しい ProxyJump を使用するのがおすすめです。

3.3 接続の維持と高速化

SSH接続は、ネットワークの状態によっては切断されたり、多重に接続を確立する際に時間がかかったりすることがあります。これらの問題を軽減し、VS Codeでのリモート開発をより快適にするための設定を紹介します。

3.3.1 接続の多重化 (ControlMaster, ControlPath, ControlPersist)

複数のSSHセッション（例: VS Codeのターミナル、ファイル同期、VS Code自体の接続）が必要な場合、通常はセッションごとに新しいSSH接続が確立されます。しかし、これらの設定を使用すると、最初の接続を「マスター接続」として確立し、以降の同じホストへの接続はそのマスター接続を再利用（多重化）するようになります。これにより、接続確立時間の短縮やリソースの節約が可能になります。VS Code Remote – SSHもこの機能を活用できます。

sshconfig
Host my-server
Hostname 192.168.1.100
User myuser
ControlMaster auto # 接続が必要なときにマスター接続を自動的に確立する
ControlPath ~/.ssh/control/%r@%h:%p # マスター接続のソケットファイルのパスを指定
ControlPersist 600 # マスター接続を最後のクライアント切断後、指定秒数維持する (0は終了まで維持)

  • ControlMaster auto: このホストへの最初のSSH接続をマスター接続として確立し、後続の接続は可能な限りそのマスター接続を再利用するようにします。
  • ControlPath ~/.ssh/control/%r@%h:%p: マスター接続が使用するソケットファイルのパスを指定します。%r, %h, %p はそれぞれユーザー名、ホスト名、ポート番号に置換されるマジックワードです。これにより、ユーザー、ホスト、ポートごとに一意のソケットファイルが生成されます。ソケットファイルを格納するためのディレクトリ（例: ~/.ssh/control) を事前に作成しておく必要があります (mkdir ~/.ssh/control)。
  • ControlPersist 600: マスター接続が維持される時間を秒単位で指定します。600 は10分間です。最後のクライアントがマスター接続から切断された後、この時間だけマスター接続が維持されます。この時間内に再び同じホストへの接続要求があれば、既存のマスター接続が再利用されます。0 を指定すると、SSHクライアント自体が終了するまでマスター接続を維持します。VS Codeで頻繁に接続/切断する場合は、ある程度の時間を設定しておくと便利です。

これらの設定により、特にVS Codeでプロジェクトを開き直したり、新しいターミナルを開いたりする際に、再接続が非常に高速になります。

3.3.2 接続維持 (KeepAlive, ServerAliveInterval, ServerAliveCountMax)

アイドル状態が続くと、ネットワーク機器（ルーター、ファイアウォールなど）によってSSH接続が強制的に切断されることがあります。これを防ぐために、定期的にキープアライブパケットを送信する設定があります。

sshconfig
Host my-server
Hostname 192.168.1.100
User myuser
ServerAliveInterval 60 # サーバーにキープアライブメッセージを送信する間隔（秒）
ServerAliveCountMax 3 # サーバーからの応答がない場合に接続を切断するまでの回数
# TCPKeepAlive yes # OSのTCPキープアライブ機能を使用するかどうか (通常デフォルトで有効)

  • ServerAliveInterval 60: クライアント側からサーバーに対して、60秒ごとに「生きていますか？」というメッセージを送信します。これは、サーバーからの応答がない場合にクライアントが接続が死んでいることを検出するために使用されます。
  • ServerAliveCountMax 3: ServerAliveInterval でメッセージを送信した後、サーバーからの応答がない状態がこの回数続いた場合に、クライアントは接続が切断されたと判断し、セッションを終了します。この例では、180秒 (60秒 * 3) 応答がなければ切断と判断します。

これらの設定は、特に不安定なネットワーク環境や、アイドルタイムアウトが短いネットワーク機器を介して接続する場合に役立ちます。

3.3.3 圧縮 (Compression)

ネットワーク帯域が細い場合や、転送するデータが多い場合に、SSH接続の通信を圧縮することができます。

sshconfig
Host my-server
Hostname 192.168.1.100
User myuser
Compression yes # 圧縮を有効にする

  • Compression yes: SSH接続におけるデータ圧縮を有効にします。これにより転送量は削減されますが、クライアントとサーバーの両方で圧縮・解凍のCPUリソースが必要になります。高速なネットワーク環境では、圧縮によるCPU負荷が帯域幅の節約効果を上回る可能性があり、かえってパフォーマンスが低下することもあるため、環境に合わせて調整が必要です。

3.4 ポートフォワーディング (ポート転送)

ポートフォワーディングは、SSH接続を介して、ローカルマシンとリモートサーバー間、あるいはリモートサーバーとその先のマシン間で、特定のポートへの通信を転送する機能です。VS Codeのリモート開発で、リモートサーバー上で実行しているWebアプリケーションやサービスにローカルのブラウザからアクセスしたい場合などに非常に便利です。

ポートフォワーディングには主に3つのタイプがあります。

3.4.1 ローカルフォワード (LocalForward)

ローカルマシン (localhost:L) で特定のポートを開き、そのポートへの通信をSSH接続を介してリモートサーバー (R_host:R_port) に転送する設定です。

sshconfig
Host my-server
Hostname 192.168.1.100
User myuser
LocalForward 8080 localhost:80 # ローカルの8080ポートへのアクセスを、リモートのlocalhost:80へ転送
LocalForward 3000 10.0.0.200:3000 # ローカルの3000ポートへのアクセスを、リモートサーバーから見た10.0.0.200の3000ポートへ転送

  • LocalForward L_port R_host:R_port:
    • L_port: ローカルマシンで開くポート番号。
    • R_host: リモートサーバーから見た転送先ホスト名またはIPアドレス。通常は localhost または 127.0.0.1 を指定して、リモートサーバー自身で実行されているサービスを指定します。
    • R_port: R_host のポート番号。

この設定でVS Codeから my-server に接続すると、ローカルマシンの localhost:8080 にアクセスすると、その通信はSSHトンネルを通ってリモートサーバーに転送され、リモートサーバーの localhost:80 で待ち受けているサービス（例: Webサーバー）に接続されます。

VS CodeのRemote – SSH拡張機能は、リモートで実行されているサービスが特定のポートでリッスンしているのを検出すると、自動的にローカルポートへのフォワードを提案してくれますが、SSH Configに記述しておけば自動的に設定されます。

3.4.2 リモートフォワード (RemoteForward)

リモートサーバー (R_host:R_port) で特定のポートを開き、そのポートへの通信をSSH接続を介してローカルマシン (L_host:L_port) に転送する設定です。これは、リモートサーバー上のサービスからローカルマシン上のサービスにアクセスしたい場合などに使用できます。

sshconfig
Host my-server
Hostname 192.168.1.100
User myuser
RemoteForward 8080 localhost:80 # リモートの8080ポートへのアクセスを、ローカルのlocalhost:80へ転送

  • RemoteForward R_port L_host:L_port:
    • R_port: リモートサーバーで開くポート番号。
    • L_host: ローカルマシンから見た転送先ホスト名またはIPアドレス。通常は localhost または 127.0.0.1 を指定して、ローカルマシン自身で実行されているサービスを指定します。
    • L_port: L_host のポート番号。

この設定でVS Codeから my-server に接続すると、リモートサーバー上のシェルなどから localhost:8080 にアクセスすると、その通信はSSHトンネルを通ってローカルマシンに転送され、ローカルマシンの localhost:80 で待ち受けているサービスに接続されます。

3.4.3 ダイナミックフォワード (DynamicForward)

ローカルマシン (localhost:L) でSOCKSプロキシポートを開き、そのプロキシを経由した通信をSSH接続を介してリモートサーバーに転送する設定です。これにより、リモートサーバーを踏み台にした汎用的なプロキシとして利用できます。

sshconfig
Host my-server
Hostname 192.168.1.100
User myuser
DynamicForward 1080 # ローカルの1080ポートでSOCKSプロキシを待ち受ける

  • DynamicForward L_port:
    • L_port: ローカルマシンで開くSOCKSプロキシポート番号。

この設定でVS Codeから my-server に接続し、ブラウザや他のアプリケーションのプロキシ設定で「SOCKSプロキシ」として「ローカルホスト (localhost)」とポート番号 1080 を指定すると、そのアプリケーションからの通信は全てSSHトンネルを通ってリモートサーバーからインターネットに出ていくようになります。これは、特定の国やネットワークからのアクセス制限を回避したり、リモートサーバーと同じネットワーク内のリソースにアクセスしたりする場合に便利です。

3.5 その他の便利な設定

リモート開発をさらに便利にするその他の設定を紹介します。

  • ForwardAgent yes:

    • ローカルのSSHエージェントをリモートサーバーに転送します。これにより、リモートサーバー上でさらに別のサーバーにSSH接続する際に、ローカルエージェントに登録された秘密鍵を使ってパスワードなしで認証できるようになります。これは、開発サーバーからステージングサーバーや本番サーバーにSSH接続してデプロイなどを行う際に非常に便利です。
    • ただし、ForwardAgent yes を設定したリモートサーバーが侵害された場合、そのサーバーからローカルエージェントを悪用されるリスクもゼロではないため、信頼できるサーバーでのみ有効化することが推奨されます。
      sshconfig
      Host my-server
      Hostname 192.168.1.100
      User myuser
      ForwardAgent yes # SSHエージェントを転送する

  • LogLevel level:

    • SSHクライアントのログレベルを設定します。接続で問題が発生した場合のデバッグに役立ちます。
    • 指定できるレベルは QUIET, FATAL, ERROR, INFO, VERBOSE, DEBUG, DEBUG1, DEBUG2, DEBUG3 です。
    • VERBOSE, DEBUG あたりを指定すると、接続確立のプロセスが詳細に表示され、トラブルシューティングの助けになります。
      sshconfig
      Host my-server
      Hostname 192.168.1.100
      User myuser
      LogLevel INFO # 通常はINFOで十分
      # LogLevel DEBUG # デバッグ時はDEBUGに設定
      VS CodeのRemote – SSH拡張機能の出力パネルでも、このLogLevel設定の影響を受ける場合があります。

  • StrictHostKeyChecking yes/no/ask:

    • 初めて接続するサーバーや、サーバーのホストキーが変更された場合に、SSHクライアントがサーバーのホストキーを ~/.ssh/known_hosts ファイルに記録されているものと照合するかどうかの設定です。
    • yes (デフォルト): ホストキーが known_hosts にない場合や一致しない場合に接続を拒否します。セキュリティ上最も安全ですが、新しいサーバーへの接続時に手間がかかります。
    • no: ホストキーのチェックを行いません。セキュリティリスクがあるため非推奨です。
    • ask: ホストキーが known_hosts にない場合や一致しない場合にユーザーに確認を求めます。
    • accept-new: ホストキーが known_hosts にない場合は自動的に追加して接続しますが、一致しない場合は接続を拒否します。利便性とセキュリティのバランスが良い選択肢です。
      sshconfig
      Host my-server
      Hostname 192.168.1.100
      User myuser
      StrictHostKeyChecking ask # 新しいホストキーの場合は確認
      # または開発環境など一時的な接続が多い場合は
      # StrictHostKeyChecking accept-new

  • UserKnownHostsFile file:

    • ホストキーを記録する known_hosts ファイルのパスを指定します。デフォルトは ~/.ssh/known_hosts です。複数のファイルに分けて管理したい場合などに使用できます。
      sshconfig
      Host my-server
      Hostname 192.168.1.100
      User myuser
      UserKnownHostsFile ~/.ssh/my_known_hosts # 特定のホストのキーを別のファイルに保存

  • PreferredAuthentications methods:

    • サーバーに対して試行する認証方法の優先順位をカンマ区切りで指定します。例えば、パスワード認証よりも公開鍵認証を優先させたい場合などに使用します。
      sshconfig
      Host my-server
      Hostname 192.168.1.100
      User myuser
      PreferredAuthentications publickey,keyboard-interactive,password # publickey -> keyboard-interactive -> password の順で試す

3.6 グローバル設定とホスト固有設定

SSH Configファイルでは、特定の Host エントリの外に記述された設定は、それに続く全ての Host エントリに適用される「グローバル設定」となります（ただし、特定のHostエントリ内で同じ設定が記述されている場合はそちらが優先されます）。

“`sshconfig

グローバル設定例

Host *
# すべてのホストに適用される設定をここに記述
ServerAliveInterval 60
ServerAliveCountMax 3
Compression yes

Host my-server-1
Hostname 192.168.1.100
User myuser1
# ここに書かれた設定は上記グローバル設定より優先される

Host my-server-2
Hostname 192.168.1.101
User myuser2
# ここに書かれた設定は上記グローバル設定より優先される
# ここに設定がない項目は上記グローバル設定が適用される
“`

Host * エントリは、ファイル中で最も後ろに記述するのが一般的です。これは、具体的なホスト名のエントリが先にマッチした場合にそちらの設定が優先され、どの Host エントリにもマッチしなかった場合（または具体的なエントリに特定の設定が記述されていない場合）にのみ Host * の設定が適用されるためです。

グローバル設定をうまく利用することで、共通の設定（例: KeepAlive関連やCompression）をまとめて記述でき、SSH Configファイルを簡潔に保つことができます。

第4章：VS CodeとSSH Configの連携

SSH Configファイルを編集し、保存すれば、VS CodeのRemote – SSH拡張機能は自動的にその変更を読み込むはずです。もし読み込まれない場合は、VS Codeを再起動するか、コマンドパレットから「Remote-SSH: Reload Configuration Files」を実行してみてください。

4.1 VS CodeからのConfigファイル編集

VS CodeからSSH Configファイルを直接編集することも可能です。

  1. VS Codeの左下のリモートインジケーターをクリックします。
  2. コマンドパレットで「Remote-SSH: Open Configuration File…」を選択します。
  3. SSH Configファイルのパスを選択または入力します。デフォルトのパスがリストに表示されるはずです。
  4. 選択したSSH ConfigファイルがVS Codeのエディタで開かれるので、ここで編集できます。

この機能を使えば、ターミナルを立ち上げることなく、VS Codeから手軽にSSH Configファイルを管理できます。

4.2 新しいホストの追加

VS CodeのRemote – SSH拡張機能のUIから新しいホストを追加することもできます。

  1. VS Codeの左下のリモートインジケーターをクリックします。
  2. コマンドパレットで「Remote-SSH: Add New SSH Host…」を選択します。
  3. 接続したいSSHコマンド（例: ssh user@hostname または ssh user@hostname -p port）を入力します。
  4. 入力したコマンドに基づいて、Remote – SSH拡張機能がSSH Configファイルに新しいエントリを追加します。既存のConfigファイルを選択するよう求められるので、通常はデフォルトのパスを選択します。
  5. Configファイルがエディタで開かれ、新しいホストエントリが追加されているので、必要に応じて設定を編集・保存します。

この機能は、SSH Configの基本的なエントリを追加するのに便利です。応用的な設定（ProxyJump, ControlMasterなど）を追加したい場合は、手動でConfigファイルを編集する必要があります。

4.3 VS Codeワークスペースとリモート接続

VS Codeでリモートサーバーに接続すると、新しいウィンドウが開きます。このウィンドウは、リモートサーバー上の特定のディレクトリを「ワークスペース」として開くことができます。

  • リモート接続したVS Codeウィンドウの「ファイル」>「フォルダーを開く」を選択し、リモートサーバー上の開発プロジェクトがあるディレクトリを選択します。
  • これにより、そのディレクトリをルートとしたファイルエクスプローラーが表示され、そのディレクトリ内でターミナルを開いたり、デバッグ構成を設定したりすることができます。

VS Codeは、接続情報（どのホストに接続しているか）と、開いているワークスペース情報（リモートサーバー上のどのディレクトリか）を記憶しています。次にそのホストに接続する際に、以前開いていたワークスペースを自動的に開くように設定することも可能です（設定 remote.SSH.rememberWorkspace）。

第5章：トラブルシューティング

VS CodeでSSH接続がうまくいかない場合に確認すべき一般的な問題と対処法を解説します。

5.1 一般的な接続エラーとその原因

  • Permission denied (publickey, password).:

    • 原因: 認証に失敗しました。最も一般的なエラーです。
    • 確認点:
      • ユーザー名: SSH Configの User またはコマンドラインで指定したユーザー名が正しいか？
      • 公開鍵認証:
        • SSH Configの IdentityFile で指定した秘密鍵ファイルのパスが正しいか？
        • 秘密鍵に対応する公開鍵がリモートサーバーの接続ユーザーの ~/.ssh/authorized_keys に正しく追記されているか？（公開鍵の内容のコピー漏れや間違いがないか）
        • リモートサーバーの ~/.ssh ディレクトリのパーミッションが 700、~/.ssh/authorized_keys ファイルのパーミッションが 600 に設定されているか？ (これらが緩いと認証が拒否される場合があります)
        • ローカルの秘密鍵ファイル (IdentityFile で指定したファイル) のパーミッションが 600 またはそれ以下になっているか？
        • 秘密鍵にパスフレーズが設定されている場合、パスフレーズが正しく入力されているか？ SSHエージェントを使っている場合、エージェントが起動していて、秘密鍵が正しく登録されているか？ (ssh-add -l で確認)
        • リモートサーバーのSSH設定 (/etc/ssh/sshd_config) で公開鍵認証 (PubkeyAuthentication yes) が有効になっているか？
      • パスワード認証:
        • 入力したパスワードが正しいか？
        • リモートサーバーのSSH設定 (/etc/ssh/sshd_config) でパスワード認証 (PasswordAuthentication yes) が有効になっているか？（セキュリティ上の理由で無効になっていることが多いです）

  • Connection refused:

    • 原因: リモートサーバーの指定されたポートでSSHサーバーが待ち受けていない、またはファイアウォールなどによって接続が拒否されています。
    • 確認点:
      • Port番号: SSH Configの Port またはコマンドラインで指定したポート番号が正しいか？ リモートサーバーでSSHサーバーが待ち受けているポート番号と一致しているか？ (netstat -tulnp | grep sshd などで確認)
      • SSHサーバー: リモートサーバーでSSHサーバー (sshd) プロセスが実行されているか？ (systemctl status sshd または service sshd status などで確認)
      • ファイアウォール: ローカルマシンのファイアウォール、リモートサーバーのファイアウォール、およびネットワーク経路上のファイアウォールが、指定したポートでのSSH接続を許可しているか？ (firewall-cmd --list-ports, ufw status, iptables -L などで確認)
      • リモートサーバーのIP/Hostname: SSH Configの Hostname が正しいリモートサーバーのIPアドレスまたはホスト名になっているか？

  • Operation timed out:

    • 原因: ネットワークが不安定、またはリモートサーバーが停止しているなどの理由で、接続要求に応答がない。
    • 確認点:
      • リモートサーバーは稼働しているか？
      • ローカルマシンからリモートサーバーまでネットワークが到達可能か？ (ping remot-server-hostname-or-ip で確認)
      • ネットワーク経路上の問題（パケットロスが多い、遅延が大きいなど）はないか？
      • ファイアウォールやセキュリティグループの設定で、接続が途中でブロックされていないか？

  • Host key verification failed.:

    • 原因: リモートサーバーのホストキーが、ローカルの ~/.ssh/known_hosts ファイルに記録されているものと異なっています。これは、サーバーが再インストールされた、IPアドレスが変わった、または中間者攻撃の可能性があります。
    • 対処法:
      • 本当にサーバーのホストキーが変更された正当な理由があるか確認します。
      • 正当な理由がある場合は、エラーメッセージに表示されている行番号を参考に、~/.ssh/known_hosts ファイルから該当する行を削除します。
      • 再度接続を試み、新しいホストキーを受け入れるか確認されますので、サーバーのホストキーのフィンガープリントが正しいことを確認した上で受け入れます。
      • StrictHostKeyChecking ask や accept-new をSSH Configに設定しておくと、このエラーへの対処が多少楽になります。

5.2 デバッグ方法

接続に問題が発生した場合、詳細な情報を取得することがトラブルシューティングの鍵となります。

5.2.1 VS Codeの出力パネル

VS CodeのRemote – SSH拡張機能は、接続に関するログを「出力」パネルに表示します。

  1. VS Codeの「表示」>「出力」を選択します。
  2. 出力パネルのドロップダウンメニューで「Remote – SSH」を選択します。
  3. 接続を試みると、ここに接続プロセスやエラーメッセージの詳細が表示されます。
5.2.2 SSHコマンドラインでのデバッグ

SSHクライアント自体が提供するデバッグオプションを使用すると、さらに詳細なログが得られます。

  • ssh -v hostname: VERBOSE レベルの詳細な接続プロセスを表示します。
  • ssh -vv hostname: DEBUG レベルのさらに詳細な情報を表示します。
  • ssh -vvv hostname: DEBUG3 レベルの最も詳細な情報を表示します。

“`bash

例: my-server への接続をデバッグ

ssh -vvv my-server
“`

このコマンドの出力を見ることで、どの段階で接続が失敗しているのか（鍵認証の試行、サーバー応答、パーミッション問題など）を特定しやすくなります。VS Codeからの接続が失敗する場合も、SSH Configファイルを使ってターミナルから同じホスト名で ssh -vvv コマンドを実行してみると、VS Code内部で何が起こっているのか手がかりが得られることがあります。

5.3 Configファイルの構文エラー

SSH Configファイルに構文エラーがあると、VS Codeがホストリストを読み込めなかったり、設定が正しく適用されなかったりします。

  • 確認点:
    • 各設定行が Host 行の下に適切にインデントされているか？
    • オプション名や値にタイプミスがないか？
    • # で始まるコメント行は正しくコメントアウトされているか？
  • 対処法:
    • VS CodeでConfigファイルを開いている場合、構文エラーがあれば通常は強調表示されます。エラー箇所を修正します。
    • エラーが解消されない場合は、設定を一つずつコメントアウトしてみて、どの設定が問題を引き起こしているかを特定します。
    • 最小限の設定 (Host, Hostname, User) だけで接続できるか試してみます。

第6章：まとめ：SSH ConfigとVS Codeでリモート開発を最適化する

このガイドでは、VS CodeのRemote – SSH拡張機能を利用したリモート開発において、SSH Configファイルがいかに重要であるか、そしてその設定方法について詳細に解説しました。

SSH Configの基本的な設定（Host, Hostname, User, Port）から始め、セキュリティを高めるための公開鍵認証とSSHエージェントの活用、ネットワーク環境に応じたプロキシ接続（ProxyJump, ProxyCommand）、接続パフォーマンスを向上させるための多重化 (ControlMaster関連) やキープアライブ (ServerAliveInterval関連)、そしてリモートサービスへのアクセスを容易にするポートフォワーディング (LocalForward, RemoteForward, DynamicForward) まで、様々な応用的な設定を網羅しました。

これらの設定を .ssh/config ファイルに適切に記述することで、VS Codeからのリモート接続は以下の点で劇的に改善されます。

  • 接続の簡素化: IPアドレスやユーザー名を毎回入力することなく、短いエイリアス名だけで接続できます。
  • セキュリティの向上: パスワード認証から安全な公開鍵認証への移行が容易になり、SSHエージェントと組み合わせることで利便性を損なわずにセキュリティを確保できます。
  • 柔軟な接続: ジャンプホスト経由や複雑なネットワーク構成にも対応できるようになります。
  • パフォーマンスの向上: 接続の多重化により、VS Codeがリモートで複数のSSHセッションを使用する際の接続確立時間が短縮されます。
  • 開発ワークフローの効率化: ポートフォワーディングにより、リモートで実行中のアプリケーションにローカルからシームレスにアクセスできます。
  • 設定の一元管理: 接続に関する様々な設定をテキストファイルとして一箇所で管理でき、チームメンバーとの共有も容易になります。

VS Code Remote – SSH拡張機能は、SSH Configファイルを強力にサポートしており、VS Codeの使い慣れたインターフェースからリモート環境をローカルとほぼ同じように扱うことを可能にします。この記事で解説したSSH Configの設定をマスターすることで、あなたのVS Codeリモート開発環境はさらに快適でパワフルなものになるでしょう。

SSH Configは非常に多くの設定オプションを持っており、この記事で紹介できたのはその一部に過ぎません。しかし、ここで解説した設定は、VS Codeを使ったほとんどのリモート開発シナリオで役立つ基本的なものから重要な応用までをカバーしています。

もし接続で問題が発生した場合は、トラブルシューティングのセクションで解説したSSHコマンドラインでのデバッグやVS Codeの出力パネルを活用し、原因を特定してください。

SSH ConfigとVS Code Remote – SSHを最大限に活用し、快適なリモート開発ライフを送りましょう。

コメントする

メールアドレスが公開されることはありません。 ※ が付いている欄は必須項目です

上部へスクロール