ネットワークのプロパティ

java.netパッケージのさまざまなクラスのメカニズムと動作を変更するために使用される、いくつかの標準システム・プロパティがあります。 一部はVMの起動時に1回だけチェックされるので、javaコマンドの-Dオプションを使用するのが適切な設定方法です。一方、他のプロパティの性質はより動的で、System.setProperty() APIを使用して変更することもできます。 このドキュメントは、これらのすべてのプロパティのリストを示し、それらの詳細を説明することを目的としています。

特にノート書きがなければ、プロパティ値は使用されるたびにチェックされます。

IPv4 / IPv6

  • java.net.preferIPv4Stack (default: false)
    オペレーティング・システムでIPv6が使用可能な場合、デフォルトでは、IPv6ソケットにより、アプリケーションはIPv4ホストとIPv6ホストの両方に接続し、接続を受け入れます。     ただし、アプリケーションでIPv4専用ソケットを使用する場合、このプロパティをtrueに設定することができます。 この場合、そのアプリケーションはIPv6専用ホストとは通信できません。

  • java.net.preferIPv6Addresses (default: false)
    IPv4とIPv6の両方のアドレスを持つホストの処理時、およびIPv6がオペレーティング・システムで使用可能な場合、デフォルトの動作では、IPv6アドレスのIPv4アドレスが使用されます。     これは、下位互換性を確保するためです: たとえば、IPv4アドレス(例、192.168.1.1)の表現に依存するアプリケーションの場合です。 このプロパティをtrueに設定すると、その設定を変更し、可能な場合はIPv4アドレスよりもIPv6アドレスを使用し、システム全体のリゾルバによって返されるアドレスの順序を保持できます。

これらのプロパティはどちらも、起動時に1回だけチェックされます。

プロキシ

プロキシ・サーバーは、ネットワーク・サービスへの間接的な接続を可能にするもので、主に、セキュリティ上の理由(ファイアウォールを通過させる)とパフォーマンス上の理由(プロキシはキャッシュ・メカニズムを提供することが多い)のために使用されます。 次のプロパティによって、さまざまな種類のプロキシを構成できます。

  • HTTP

    次のプロキシ設定がHTTPプロトコル・ハンドラによって使用されます。

    • http.proxyHost (default: <none>)
      プロキシ・サーバーのホスト名(アドレス)。

    • http.proxyPort (default: 80)
      プロキシ・サーバーのポート番号。

    • http.nonProxyHosts (default : localhost|127.*|[::1])
      プロキシを経由せずにアクセスが必要なホストを示します。       通常これは内部ホストを定義します。 このプロパティの値は、'|'文字で区切られたホストのリストです。 また、パターン一致にはワイルドカード文字'*'を使用できます。 たとえば、-Dhttp.nonProxyHosts="*.foo.com|localhost"は、プロキシ・サーバーが指定されている場合でも、foo.comドメインおよびlocalhost内のすべてのホストに直接アクセスする必要があることを示します。

      デフォルト値には、ループバック・アドレスのあらゆる一般的なバリエーションが含まれません。

  • HTTPS
    これはHTTP over SSLのことで、支払いサイトでのように、機密性が必要とされるときに使われるセキュアなバージョンのHTTPです。

    次のプロキシ設定がHTTPSプロトコル・ハンドラによって使用されます。

    • https.proxyHost (default: <none>)
      プロキシ・サーバーのホスト名(アドレス)。

    • https.proxyPort (default: 443)
      プロキシ・サーバーのポート番号。

      HTTPSプロトコル・ハンドラは、HTTPプロトコルと同じnonProxyHostsプロパティを使用します。

  • FTP

    次のプロキシ設定がFTPプロトコル・ハンドラによって使用されます。

    • ftp.proxyHost (default: <none>)
      プロキシ・サーバーのホスト名(アドレス)。

    • ftp.proxyPort (default: 80)
      プロキシ・サーバーのポート番号。

    • ftp.nonProxyHosts (default : localhost|127.*|[::1])
      プロキシを経由せずにアクセスが必要なホストを示します。       通常これは内部ホストを定義します。 このプロパティの値は、'|'文字で区切られたホストのリストです。 また、パターン一致にはワイルドカード文字'*'を使用できます。 たとえば、-Dhttp.nonProxyHosts="*.foo.com|localhost"は、プロキシ・サーバーが指定されている場合でも、foo.comドメインおよびlocalhost内のすべてのホストに直接アクセスする必要があることを示します。

      デフォルト値には、ループバック・アドレスのあらゆる一般的なバリエーションが含まれません。

  • SOCKS
    これは別の種類のプロキシです。     TCPレベルで動作するため、下位レベルのトンネリングが可能です。 実際には、SOCKSプロキシ・サーバーを設定しているJava(tm)プラットフォームでは、ほかのプロキシが指定されていなければ、すべてのTCP接続がそのプロキシを通過するようになります。 Java SEの実装でSOCKSがサポートされている場合、次のプロパティが使用されます。

    • socksProxyHost (default: <none>)
      プロキシ・サーバーのホスト名(アドレス)。

    • socksProxyPort (default: 1080)
      プロキシ・サーバーのポート番号。

    • socksProxyVersion (default: 5)
      サーバーでサポートされているSOCKSプロトコルのバージョン。       デフォルトはSOCKS V5を示す5です。 または、SOCKS V4に4を指定することもできます。 これら以外の値にプロパティを設定すると、未指定の動作が発生します。

    • java.net.socks.username (default: <none>)
      SOCKSv5サーバーが認証を要求し、java.net.Authenticatorインスタンスが見つからなかった場合に使用するユーザー名。

    • java.net.socks.password (default: <none>)
      SOCKSv5サーバーが認証を要求し、java.net.Authenticatorインスタンスが見つからなかった場合に使用するパスワード。

      上のプロパティまたはオーセンティケータのどちらも認証を提供していない場合、プロキシが認証を要求すると、パスワードなしでuser.nameプロパティが使用されます。

  • java.net.useSystemProxies (default: false)
    Windowsシステム、macOSシステムおよびGnomeシステムでは、このプロパティをtrueに設定してjava.netスタックにシステム・プロキシ設定(これらすべてのシステムでは、ユーザー・インタフェースを介してグローバルにプロキシを設定できます。)を使用するように指示できます。     このプロパティは起動時に1回だけチェックされることに注意してください。

その他のHTTP URLストリーム・プロトコル・ハンドラのプロパティ

  • http.agent (default: "Java/<version>")
    HttpリクエストのUser-Agentリクエスト・ヘッダーに送信される文字列を定義します。     文字列"Java/<version>"は、プロパティ(たとえば、-Dhttp.agent="foobar"が使用されている場合、VMのバージョンが1.5.0であれば、User-Agentヘッダーに"foobar Java/1.5.0"が含まれます。)で指定された文字列に追加されます。 このプロパティは起動時に1回だけチェックされます。

  • http.keepAlive (default: true)
    永続的な接続をサポートするかどうかを示します。     基礎となるソケット接続を複数のHTTPリクエストで再利用できるため、パフォーマンスが向上します。 これがtrueに設定されている場合は、HTTP 1.1サーバーとの間で持続接続が要求されます。

  • http.maxConnections (default: 5)
    HTTPキープ・アライブが有効な場合、(前述を参照)この値は、宛先ごとに同時に保持されるアイドル接続の最大数を決定します。

  • http.keepAlive.time.serverおよびhttp.keepAlive.time.proxy

    サーバー(またはプロキシ)でキープアライブ時間が指定されていない場合、これらのプロパティはHTTPキープアライブ・キャッシュの動作を変更します。 この場合、プロパティが設定されると、アイドル接続は指定された秒数後に閉じられます。 プロパティが設定され、サーバーが"Keep-Alive"レスポンス・ヘッダーにキープアライブ時間を指定した場合、サーバーによって指定された時間が使用されます。 プロパティが設定されておらず、かつサーバーにキープアライブ時間が指定されていない場合、http.keepAliveがtrueであると仮定して、接続は実装で定義された時間有効のままです。

  • http.maxRedirects (default: 20)
    この整数値は、自動的にプロトコル・ハンドラが後に続くHTTPリダイレクトの、指定されたリクエストの最大数を決定します。

  • http.auth.digest.validateServer (default: false)

  • http.auth.digest.validateProxy (default: false)

  • http.auth.digest.cnonceRepeat (default: 5)

    これら3つのプロパティは、HTTPダイジェスト認証機能の動作を変更します。 ダイジェスト認証は、サーバーがそのユーザーのパスワードを認識していることをクライアントに証明することによって、サーバー自体をクライアントに認証させるための限定された機能をサーバーに提供します。 ただし、すべてのHTTPサーバーがこの機能をサポートしているわけではなく、デフォルトでオフになっています。 最初の2つのプロパティは、trueに設定すると、それぞれオリジン・サーバーまたはプロキシ・サーバーとの認証で、このチェック機能を使用することができます。

    通常は、3つ目のプロパティを変更する必要はありません。 これは、cnonce値を再使用する回数を決定します。 このプロパティは、MD5-sessアルゴリズムを使用する場合に役に立ちます。 この値を増やすと、各HTTP要求のためにハッシュしなければならない情報の量が減るので、クライアントとサーバーの両方で計算のオーバーヘッドが減少します。

  • http.auth.ntlm.domain (default: <none>)
    NTLMは別の認証スキームです。     必要に応じて、java.net.Authenticatorクラスを使用してユーザー名とパスワードを取得します。 しかし、NTLMの場合はNTドメイン名も必要です。 そのドメインを指定するには、次の3つの方法があります。

    1. ドメインを指定しない。 環境によっては、実際にはドメインが必要とされないので、アプリケーションで指定する必要がありません。

    2. ドメイン名にプレフィクスとしてドメイン名を付け、その後にユーザー名の前にバックスラッシュ'\'を付けることで、ユーザー名内でドメイン名をエンコードできます。 この方法では、ユーザーがこの表記方法を使用しなければならないということを意識すれば、Authenticatorクラスを使用する既存のアプリケーションを変更する必要がありません。

    3. メソッド2のようにドメイン名が指定されておらず、このプロパティが定義されている場合は、その値がドメイン名として使用されます。

  • http.auth.digest.reEnabledAlgorithms (default: <none>)
    デフォルトでは、特定のメッセージ・ダイジェスト・アルゴリズムは、セキュリティ上の制限が実証されているため、HTTPダイジェスト認証で使用できません。     これは、プロキシ認証およびプレーン・テキストHTTPサーバー認証にのみ適用されます。 無効なアルゴリズムは引き続きHTTPSサーバー認証に使用できます。 無効化されたアルゴリズムのデフォルトのリストは、java.securityプロパティ・ファイルで指定され、現在はMD5およびSHA-1で構成されています。 これらのアルゴリズムのいずれかを使用する必要がある場合は、このプロパティをアルゴリズム名のカンマ区切りリストに設定して再度有効にできます。

  • jdk.https.negotiate.cbt (default: <never>)
    KerberosまたはKerberosを使用したネゴシエーション認証スキームがHttpsURLConnectionでHTTPSを介して使用される場合、TLSチャネル・バインディング・トークン(CBT)の生成および送信を制御します。     次の3つの設定が可能です:

    1. "never"。 これは、プロパティが設定されていない場合もデフォルト値です。 この場合、CBTは送信されません。

    2. "always"。 CBTは、HTTPSを介してすべてのKerberos認証試行に対して送信されます。

    3. "domain:<comma separated domain list>" リスト内の各ドメインは、CBTが送信される宛先ホストを指定します。 ドメインには、fooやfoo.comなどの単一ホスト、またはRFC 2732で指定されたリテラルIPアドレス、または*.foo.comのようにfoo.comおよびそのサブドメイン下のすべてのホストに一致するワイルドカードを使用できます。 CBTは、リスト・エントリのいずれかと一致しない宛先には送信されません

    生成されるチャネル・バインディング・トークンは、RFC 5929で定義されているタイプ"tls-server-end-point"です。

これらのプロパティはすべて、起動時に1回だけチェックされます。

アドレス・キャッシュ

名前解決の実行時、java.netパッケージはセキュリティ上とパフォーマンス上の両方の理由で、アドレス・キャッシュを使用します。 アドレス解決の試行は、前方解決(名前からIPアドレスへ)でも逆方向の解決(IPアドレスから名前へ)でもすべて、成功であったかどうかを問わず結果がキャッシュされます。そのため、以後の同一の要求はネーム・サービスにアクセスする必要がなくなります。 これらのプロパティでは、キャッシュの動作方法をいくつかの設定でチューニングできます。

  • networkaddress.cache.ttl (default: 下記参照)
    値は、名前参照が成功した秒数に対応する整数で、キャッシュに保持されます。     -1の値や、その他の負の値はすべて、「ずっとキャッシュする」ことを意味します。値0は、キャッシュを使用しないという意味です。 デフォルト値は、セキュリティ・マネージャがインストールされている場合は-1 (forever)で、セキュリティ・マネージャがインストールされていない場合は実装固有です。

  • networkaddress.cache.negative.ttl (default: 10)
    値は、失敗した名前参照がキャッシュに保持される秒数に対応する整数です。     -1の値や、その他の負の値はすべて、「ずっとキャッシュする」ことを意味します。値0は、キャッシュを使用しないという意味です。

これら2つのプロパティはセキュリティ・ポリシーの一部であるため、 -DオプションまたはSystem.setProperty() APIによって設定されるのではなく、セキュリティ・プロパティとして設定されます。

Unixドメイン・ソケット

nullアドレス・パラメータを指定してServerSocketChannel.bindをコールすると、「自動割当済」ソケット・アドレスにバインドされます。 Unixドメイン・ソケットの場合、これは事前定義されたシステム一時ディレクトリ内の一意のパスを意味します。 この動作に影響を与えるシステム(ネットワーキング)プロパティは多数あります。

Unixドメイン・ソケット・アドレスの長さは約100バイトの(プラットフォームによって異なります)に制限されています。一時ディレクトリ名とソケット(現在、socket_1679697142に類似した名前)に使用されるファイル名がこの制限を超えないようにすることが重要です。 次のプロパティを使用して、このディレクトリの選択を制御できます:

  • jdk.net.unixdomain.tmpdirこれは、conf/net.propertiesでネットワーキング・プロパティとして設定できます。設定した場合、自動的にバインドされるサーバー・ソケット・アドレスに使用するディレクトリを指定します。 一部のプラットフォームでは、(一部のUnixシステムなど)にデフォルト値が事前定義されています。 それ以外の場合、(例: Windows)にはデフォルト値はありません。 どちらの方法でも、コマンド行で設定された同じ名前のシステム・プロパティでネットワーク・プロパティをオーバーライドできます。 ネットワークもシステム・プロパティも設定されていない場合、一部のシステム(例: Windows)では、一般的に使用される環境変数が一時ディレクトリとしてチェックされることがあります。

  • java.io.tmpdir前のステップで使用するディレクトリが見つからない場合は、システム・プロパティjava.io.tmpdirで識別されるディレクトリが使用されます。

プラットフォーム固有の動作の詳細は、conf/net.properties構成ファイルを参照してください。

SocketChannelのImplicitバインディング

クライアント・ソケットがbindをコールせずにリモート宛先に接続されている場合、ソケットは「暗黙的」バウンドです。 この場合、「Unixドメイン」ソケットは「名前なし」 (ie.パスが空です)です。 この動作は、システムまたはネットワークのプロパティの影響を受けません。

拡張例外メッセージ

デフォルトでは、セキュリティ上の理由から、例外メッセージにはホスト名やUnixドメイン・ソケット・アドレス・パスなどの機密性の高いセキュリティ情報は含まれません。 次のプロパティは、デバッグなどの目的でこの制限を緩和するために使用できます。

  • jdk.includeInExceptionsこれは通常、より詳細な情報でメッセージを拡張できる例外タイプを参照するキーワードのカンマ区切りリストに設定されます。 値に文字列hostInfoが含まれている場合、ソケット・アドレスは例外メッセージ・テキスト(例:ホスト名、Unixドメイン・ソケット・アドレス・パス)に含まれます。