Linux 上の Python コードのリモート デバッグRemotely debugging Python code on Linux

Visual Studio は、Windows コンピューター上でローカルまたはリモートで Python アプリケーションを起動およびデバッグすることができます (「Remote Debugging」 (リモート デバッグ) をご覧ください)。Visual Studio can launch and debug Python applications locally and remotely on a Windows computer (see Remote debugging). また、別のオペレーティング システム、デバイス、または CPython 以外の Python 実装を ptvsd ライブラリを使用してリモートでデバッグすることもできます。It can also debug remotely on a different operating system, device, or Python implementation other than CPython using the ptvsd library.

ptvsd を使用する場合、デバッグ対象の Python コードは Visual Studio がアタッチできるデバッグ サーバーをホストします。When using ptvsd, the Python code being debugged hosts the debug server to which Visual Studio can attach. このホストには、コードに小さな変更を加えてサーバーをインポートして有効にする必要があります。また、TCP 接続を許可するようにリモート コンピューター上でネットワークまたはファイアウォールを構成する必要が生じる場合があります。This hosting requires a small modification to your code to import and enable the server, and may require network or firewall configurations on the remote computer to allow TCP connections.

リモート デバッグの概要については、Visual Studio 2015 と 2017 の両方に該当する「Deep Dive: Cross-Platform Remote Debugging」(詳細情報: クロスプラットフォームのリモート デバッグ) (youtube.com、6 分 22 秒) をご覧ください。For an introduction to remote debugging, see Deep Dive: Cross-Platform Remote Debugging (youtube.com, 6m22s), which is applicable to both Visual Studio 2015 and 2017.

Linux コンピューターのセットアップSetting up a Linux computer

このチュートリアルを実行するには、次の項目が必要です。The following items are needed to follow this walkthrough:

  • Mac OSX や Linux などのオペレーティング システムで Python を実行しているリモート コンピューター。A remote computer running Python on an operating system like Mac OSX or Linux.
  • そのコンピューターのファイアウォールで開いているポート 5678 (受信)。これはリモート デバッグの既定値です。Port 5678 (inbound) opened on that computer's firewall, which is the default for remote debugging.

Azure に Linux 仮想マシンを簡単に作成し、Windows からリモート デスクトップを使用してアクセスできます。You can easily create Linux virtual machines on Azure and access it using Remote Desktop from Windows. VM に Ubuntu を使用すると、既定で Python がインストールされるので便利です。Ubuntu を使用しない場合、Python をダウンロードできるその他の場所については、「Install a Python interpreter of your choice」(好みの Python インタープリターをインストールする) の一覧を参照してください。An Ubuntu for the VM is convenient because Python is installed by default; otherwise, see the list on Install a Python interpreter of your choice for additional Python download locations.

Azure VM のファイアウォール ルールの作成方法については、「Azure Portal を使用した Azure の VM へのポートの開放」を参照してください。For details on creating a firewall rule for an Azure VM, see Opening ports to a VM in Azure using the Azure portal.

デバッグのためのスクリプトの準備Preparing the script for debugging

  1. リモート コンピューターで、次のコードを含む guessing-game.py という Python ファイルを作成します。On the remote computer, create a Python file called guessing-game.py with the following code:

    import random
    
    guesses_made = 0
    name = input('Hello! What is your name?\n')
    number = random.randint(1, 20)
    print('Well, {0}, I am thinking of a number between 1 and 20.'.format(name))
    
    while guesses_made < 6:
       guess = int(input('Take a guess: '))
       guesses_made += 1
       if guess < number:
           print('Your guess is too low.')
       if guess > number:
           print('Your guess is too high.')
       if guess == number:
           break
    if guess == number:
       print('Good job, {0}! You guessed my number in {1} guesses!'.format(name, guesses_made))
    else:
       print('Nope. The number I was thinking of was {0}'.format(number))
    
  2. pip3 install ptvsd を使用して環境に ptvsd パッケージをインストールします。Install the ptvsd package into your environment using pip3 install ptvsd. (注: トラブルシューティングが必要な場合に備えて、インストールされている ptvsd のバージョンを記録しておくことをお勧めします。ptvsd 一覧にも使用できるバージョンが記載されています)。(Note: it's a good idea to record the version of ptvsd that's installed in case you need it for troubleshooting; the ptvsd listing also shows available versions.)

  3. 下のコードを他のコードよりも前の、guessing-game.pyのできるだけ早い段階で追加して、リモート デバッグを有効にします。Enable remote debugging by adding the code below at the earliest possible point in guessing-game.py, before other code. (厳密な要件ではありませんが、enable_attach 関数を呼び出す前に起動されたバックグラウンド スレッドをデバッグすることはできません。)(Though not a strict requirement, it's impossible to debug any background threads spawned before the enable_attach function is called.)

    import ptvsd
    ptvsd.enable_attach('my_secret')
    

    enable_attach に渡される最初の引数 ("シークレット" と呼ばれます) は、実行中のスクリプトへのアクセスを制限します。このシークレットは、リモート デバッガーをアタッチするときに入力しますThe first argument passed to enable_attach (called "secret") restricts access to the running script, and you enter this secret when attaching the remote debugger. (推奨されませんが、enable_attach(secret=None) の接続と使用を任意のユーザーに許可することもできます)。(Though not recommended, you can allow anyone to connect, use enable_attach(secret=None).)

  4. ファイルを保存して python3 guessing-game.py を実行します。Save the file and run python3 guessing-game.py. enable_attach を呼び出すとバックグラウンドで実行され、受信接続を待機します。それ以外の場合はプログラムと対話しています。The call to enable_attach runs in the background and waits for incoming connections as you otherwise interact with the program. 必要な場合は、wait_for_attach 関数を enable_attach の後に呼び出して、デバッガーがアタッチされるまでプログラムをブロックすることもできます。If desired, the wait_for_attach function can be called after enable_attach to block the program until the debugger attaches.

ヒント

enable_attachwait_for_attach に加えて、ptvsdにはヘルパー関数 break_into_debugger も用意されています。この関数は、デバッガーがアタッチされている場合にプログラムのブレークポイントとして機能します。In addition to enable_attach and wait_for_attach, ptvsd also provides a helper function break_into_debugger, which serves as a programmatic breakpoint if the debugger is attached. また、デバッガーがアタッチされている場合に True を返す is_attached 関数もあります (他の ptvsd 関数を呼び出す前にこの結果を確認する必要はありません)。There is also an is_attached function that returns True if the debugger is attached (note that there is no need to check this result before calling any other ptvsd functions).

Python Tools からのリモート アタッチAttaching remotely from Python Tools

以下の手順では、リモート プロセスを停止する単純なブレークポイントを設定します。In these steps, we set a simple breakpoint to stop the remote process.

  1. ローカル コンピューターでリモート ファイルのコピーを作成し、Visual Studio で開きます。Create a copy of the remote file on the local computer and open it in Visual Studio. ファイルの場所は任意ですが、名前はリモート コンピューターのスクリプト名と一致している必要があります。It doesn't matter where the file is located, but its name should match the name of the script on the remote computer.

  2. (省略可能) ローカル コンピューター上の ptvsd 用に IntelliSense を使用するには、ptvsd パッケージを Python 環境にインストールします。(Optional) To have IntelliSense for ptvsd on your local computer, install the ptvsd package into your Python environment.

  3. [デバッグ]、[プロセスにアタッチ] の順に選択します。Select Debug > Attach to Process.

  4. 表示される [プロセスにアタッチ] ダイアログで、[接続の種類][Python remote (ptvsd)] (Python リモート (ptvsd)) に設定しますIn the Attach to Process dialog that appears, set Connection Type to Python remote (ptvsd). (旧バージョンの Visual Studio では、これらのコマンドは [トランスポート][Python リモート デバッグ] という名称でした)。(On older versions of Visual Studio these commands are named Transport and Python remote debugging.)

  5. [接続先] フィールド (旧バージョンでは [修飾子]) に「tcp://<secret>@<ip_address>:5678」と入力します。<secret> は Python コードで渡される文字列 enable_attach です。<ip_address> はリモート コンピューターの IP アドレスです (明示的なアドレスまたは myvm.cloudapp.net のような名前を指定できます)。:5678 はリモート デバッグ ポート番号です。In the Connection Target field (Qualifier on older versions), enter tcp://<secret>@<ip_address>:5678 where <secret> is the string passed enable_attach in the Python code, <ip_address> is that of the remote computer (which can be either an explicit address or a name like myvm.cloudapp.net), and :5678 is the remote debugging port number.

    警告

    パブリック インターネット経由で接続している場合は、代わりに tcps を使用し、以下の「デバッガー接続の SSL によるセキュリティ保護」の指示に従ってください。If you're making a connection over the public internet, you should be using tcps instead and following the instruction below for Securing the debugger connection with SSL.

  6. Enter キーを押すと、そのコンピューターで使用できる ptvsd プロセスの一覧が生成されます。Press Enter to populate the list of available ptvsd processes on that computer:

    接続のターゲットの入力とプロセスの一覧表示

    この一覧の生成後にリモート コンピューターで別のプログラムを起動する場合は、[更新] ボタンを選択します。If you happen to start another program on the remote computer after populating this list, select the Refresh button.

  7. プロセスを選択してデバッグし、[アタッチ] を選択するか、プロセスをダブルクリックします。Select the process to debug and then Attach, or double-click the process.

  8. Visual Studio はデバッグ モードに切り替わり、スクリプトは引き続きリモート コンピューターで実行され、通常のデバッグ機能もすべて使用できます。Visual Studio then switches into debugging mode while the script continues to run on the remote computer, providing all the usual debugging capabilities. たとえば、if guess < number: 行のブレークポイントを設定し、リモート コンピューターに切り替え、別の推測を入力します。For example, set a breakpoint on the if guess < number: line, then switch over to the remote computer and enter another guess. その後、ローカル コンピューターの Visual Studio はそのブレークポイントで停止し、ローカル変数などが表示されます。After you do so, Visual Studio on your local computer stops at that breakpoint, shows local variables, and so on:

    ブレークポイントにヒットした状態

  9. デバッグを停止すると、Visual Studio はプログラムからデタッチされますが、リモート コンピューターでは実行が継続されます。When you stop debugging, Visual Studio detaches from the program, which continues to run on the remote computer. また、ptvsd もデバッガーのアタッチを引き続きリッスンするので、いつでもプロセスに再アタッチできます。ptvsd also continues listening for attaching debuggers, so you can reattach to the process again at any time.

接続のトラブルシューティングConnection troubleshooting

  1. [接続の種類][Python remote (ptvsd)](Python リモート (ptvsd)) (旧バージョンでは [トランスポート][Python remote debugging](Python リモート デバッグ)) を選択していることを確認します。Make sure that you've selected Python remote (ptvsd) for the Connection Type (Python remote debugging for Transport with older versions.)
  2. [Connection Target](接続のターゲット) (または [修飾子]) のシークレットがリモート コードのシークレットと完全に一致することを確認します。Check that the secret in the Connection Target (or Qualifier) exactly matches the secret in the remote code.
  3. [接続先] (または [修飾子]) の IP アドレスがリモート コンピューターと一致することを確認します。Check that the IP address in the Connection Target (or Qualifier) matches that of the remote computer.
  4. リモート コンピューターのリモート デバッグ ポートを開いていること、接続先に :5678 などのポート サフィックスを含めていることを確認します。Check that you're opened the remote debugging port on the remote computer, and that you've included the port suffix in the connection target, such as :5678.
    • 別のポートを使用する必要がある場合は、enable_attach の呼び出しで ptvsd.enable_attach(secret = 'my_secret', address = ('0.0.0.0', 8080)) のように address 引数を使用して指定できます。If you need to use a different port, you can specify it in the enable_attach call using the address argument, as in ptvsd.enable_attach(secret = 'my_secret', address = ('0.0.0.0', 8080)). この場合、ファイアウォールでもそのポートを開きます。In this case, open that specific port in the firewall.
  5. pip3 list から返されたリモート コンピューターにインストールされている ptvsd のバージョンが、Visual Studio で使用している Python ツールのバージョンで使用されている ptvsd のバージョン (以下の表を参照してください) が一致することを確認します。Check that the version of ptvsd installed on the remote computer as returned by pip3 list matches that used by the version of the Python tools you're using in Visual Studio in the table below. 必要に応じて、リモート コンピューターの ptvsd を更新します。If necessary, update ptvsd on the remote computer.

    Visual Studio のバージョンVisual Studio Version Python ツール/ptvsd のバージョンPython tools/ptvsd version
    2017 15.32017 15.3 3.2.03.2.0
    2017 15.22017 15.2 3.1.03.1.0
    2017 15.0, 15.12017 15.0, 15.1 3.0.03.0.0
    20152015 2.2.62.2.6
    20132013 2.2.22.2.2
    2012, 20102012, 2010 2.12.1

デバッガー接続の SSL によるセキュリティ保護Securing the debugger connection with SSL

ptvsd のリモート デバッグ サーバーへの接続は、既定で、シークレットのみで保護されており、すべてのデータはプレーンテキストで渡されます。By default, the connection to the ptvsd remote debug server is secured only by the secret and all data is passed in plain text. より高いセキュリティの接続には、ptvsd でサポートされている SSL を使用します。設定手順は次のとおりです。For a more secure connection, ptvsd supports SSL, which you set up as follows:

  1. リモート コンピューターで、openssl を使用して別の自己署名証明書とキー ファイルを生成します。On the remote computer, generate separate self-signed certificate and key files using openssl:

    openssl req -new -x509 -days 365 -nodes -out cert.cer -keyout cert.key
    

    openssl のプロンプトが表示されたら、[共通名] のホスト名または IP アドレス (接続できればどちらでも可) を入力しますWhen prompted, use the hostname or IP address (whichever you use to connect) for the Common Name when prompted by openssl.

    (詳細については、Python ssl モジュール ドキュメントの「Self-signed certificates」(自己署名証明書) を参照してください。(See Self-signed certificates in the Python ssl module docs for additional details. これらのドキュメントのコマンドは、1 つの結合されたファイルのみを生成する点に注意してください)。Note that the command in those docs generates only a single combined file.)

  2. このコードで、enable_attach の呼び出しを修正し、値としてファイル名を使用して certfile 引数と keyfile 引数を含めます (これらの引数の意味は、標準の ssl.wrap_socket Python 関数の引数と同じです)。In the code, modify the call to enable_attach to include certfile and keyfile arguments using the filenames as the values (these arguments have the same meaning as for the standard ssl.wrap_socket Python function):

    ptvsd.enable_attach(secret='my_secret', certfile='cert.cer', keyfile='cert.key')
    

    また、ローカル コンピューターのコード ファイルでも同じ変更を加えることもできます。ただし、このコードは実際には実行されないので、厳密には必要ありません。You can also make the same change in the code file on the local computer, but because this code isn't actually run, it isn't strictly necessary.

  3. リモート コンピューターで Python プログラムを再起動し、デバッグできる状態にします。Restart the Python program on the remote computer, making it ready for debugging.

  4. Visual Studio がインストールされた Windows コンピューターの [信頼されたルート CA] にその証明書を追加して、チャネルをセキュリティで保護します。Secure the channel by adding the certificate to Trusted Root CA on the Windows computer with Visual Studio:

    1. リモート コンピューターの証明書ファイルをローカル コンピューターにコピーします。Copy the certificate file from the remote computer to the local computer.
    2. コントロール パネルを開き、[管理ツール] > [コンピューター証明書の管理] に移動します。Open Control Panel and navigate to Administrative Tools > Manage computer certificates.
    3. 表示されるウィンドウで、左側の [信頼されたルート証明機関] を展開し、[証明書] を右クリックして [すべてのタスク] > [インポート] を選択します。In the window that appears, expand Trusted Root Certification Authorities on the left side, right-click Certificates, and select All Tasks > Import....
    4. リモート コンピューターからコピーした .cer ファイルに移動して選択し、ダイアログの指示に従ってクリックしてインポートを完了します。Navigate to and select the .cer file copied from the remote computer, then click through the dialogs to complete the import.
  5. 前述の手順で Visual Studio のアタッチ プロセスを繰り返します。今回は、[Connection Target](接続のターゲット) (または [修飾子]) として tcps:// を使用します。Repeat the attach process in Visual Studio as described earlier, now using tcps:// as the protocol for the Connection Target (or Qualifier).

    SSL を使用するリモート デバッグ トランスポートの選択

警告Warnings

後述のように、Visual Studio で SSL で接続するときに証明書の問題の可能性が表示されます。Visual Studio prompts you about potential certificate issues when connecting over SSL as described below. この警告を無視して続行しても問題ありません。無視しても、man-in-the-middle 攻撃を受ける可能性がある傍受を防ぐために、チャネルは暗号化されます。You may ignore the warnings and proceed, but although the channel is still be encrypted against eavesdropping it can be open to man-in-the-middle attacks.

  1. 以下の "リモート証明書は信頼されていません" という警告が表示される場合は、[信頼されたルート CA] に証明書が適切に追加されていないことを示します。If you see the "remote certificate is not trusted" warning below, it means you did not properly add the certificate to the Trusted Root CA. 追加手順を確認して、もう一度試してください。Check those steps and try again.

    SSL 証明書の信頼の警告

  2. 以下の "リモート証明書名がホスト名と一致しません" という警告が表示される場合は、証明書の作成時に [共通名] として正しいホスト名または IP アドレスを指定していないことを示します。If you see the "remote certificate name does not match hostname" warning below, it means you did not use the proper hostname or IP address as the Common Name when creating the certificate.

    SSL 証明書のホスト名の警告

警告

現在、これらの警告を無視すると、Visual Studio 2017 はハングします。At present, Visual Studio 2017 hangs when you ignore these warnings. すべての問題を修正してから、接続を試行してください。Be sure to correct all problems before attempting to connect.