3. HAProxyの起動
HAProxyは、コマンドラインでいくつかの引数を渡して"haproxy"プログラムを呼び出すことで起動します。実際の構文は次のとおりです。
ここで、[<options>]*は任意の個数のオプションです。オプションは常に’-‘で始まり、一つ以上の文字が続き、さらに一つまたは複数の引数が続くことがあります。オプションを指定しない場合、HAProxyは対応するオプションを示すヘルプページを表示します。利用可能なオプションは、OSによって多少異なる場合があります。多くのオプションには、“global"セクションに同等の設定があります。この場合、コマンドラインは常に設定ファイルより優先されるため、設定ファイルに手を加えずに、コマンドラインから特定の設定をすばやく適用できます。現在のオプション一覧は次のとおりです。
-- <cfgfile>*
“–“の後に続くすべての引数は、宣言した順序で読み込んで処理する設定ファイル／ディレクトリのパスです。主に、数値順に並んだ多数のファイルをシェルに読み込ませる場合に役立ちます。"-f"も参照してください。”–“と”-f"の違いは、"-f"は各ファイル名の前に一つずつ必要なのに対し、”–“はすべてのファイル名の前に一つだけ必要な点です。両方を併用することもでき、その場合もコマンドラインの順序が適用されます。複数のファイルを指定する場合、各ファイルはセクションの境界から始めなければなりません。つまり、各ファイルの最初のキーワードは、“global”、“defaults”、“peers”、“listen”、“frontend”、“backend"などのいずれかでなければなりません。たとえば、サーバーの一覧だけを含むファイルにはできません。
-f <cfgfile|cfgdir>
読み込む設定ファイルの一覧に<cfgfile>を追加します。<cfgdir>がディレクトリの場合、その中にあるすべてのファイル（ファイルだけ）を、辞書順（LC_COLLATE=Cを使用）で読み込み対象の設定ファイル一覧に追加します。追加するのは拡張子が”.cfg"のファイルだけで、隠しファイル（先頭が”.“のファイル）は追加しません。設定ファイルは宣言した順序で読み込み、処理します。このオプションを複数回指定して、複数のファイルを読み込めます。”–“も参照してください。”–“と”-f"の違いは、"-f"は各ファイル名の前に一つずつ必要なのに対し、”–“はすべてのファイル名の前に一つだけ必要な点です。両方を併用することもでき、その場合もコマンドラインの順序が適用されます。複数のファイルを指定する場合、各ファイルはセクションの境界から始めなければなりません。つまり、各ファイルの最初のキーワードは、“global”、“defaults”、“peers”、“listen”、“frontend”、“backend"などのいずれかでなければなりません。たとえば、サーバーの一覧だけを含むファイルにはできません。
-C <dir>
設定ファイルを読み込む前に、ディレクトリ<dir>へ移動します。相対パスを使う場合に便利です。”–“の後にワイルドカードを使う場合は、実際にはhaproxyの起動前にシェルが展開する点に注意してください。
-D
デーモンとして起動します。プロセスはfork後に現在の端末から切り離され、端末にはエラーが報告されなくなります。設定の"global"セクションにある"daemon"キーワードと同等です。不正な設定によってシステムの起動が妨げられないよう、すべてのinitスクリプトで常にこれを強制することを推奨します。
-L <name>
ローカルピア名を<name>に変更します。デフォルトはローカルホスト名です。これはpeersレプリケーションでのみ使用します。設定ファイルで変数$HAPROXY_LOCALPEERを使うと、ピア名を参照できます。
-N <limit>
プロキシごとのデフォルトのmaxconnを、組み込みのデフォルト値（通常は2000）から<limit>へ変更します。デバッグにのみ有用です。
-V
詳細モードを有効にします（静粛モードを無効にします）。"-q"または"quiet"の効果を取り消します。
-W
マスターワーカーモードです。設定の"global"セクションにある"master-worker"キーワードと同等です。このモードは"workers"を監視する"master"を起動します。マスターへSIGUSR2シグナルを送ることで、HAProxyを直接リロードできます。マスターワーカーモードは、フォアグラウンドモードとデーモンモードのどちらとも併用できます。マルチプロセスおよびsystemdでは、このモードの使用を推奨します。
-Ws
systemdサービスのnotify型をサポートするマスターワーカーモードです。
-4
DNSリゾルバーがIPv4アドレス（“A"レコード）だけを問い合わせ、受け入れるよう強制します。エンドツーエンドのデュアルスタック接続がない一部の環境で問題が起きる場合に使えます。globalの"dns-accept-family"ディレクティブを上書きし、“ipv4"を強制します。
-c
設定ファイルのチェックだけを行い、バインドを試みる前に終了します。すべて正常なら終了ステータスはゼロ、エラーがあればゼロ以外です。警告があればその存在を報告します。デフォルトでは、成功メッセージは出力しません。"-V"と組み合わせると、成功時に"Configuration file is valid"というメッセージを出力します。
スクリプトは、コマンドの成功判定に終了ステータスを使わなければなりません。
-cc
設定の条件付きブロックで使う条件を評価します。条件が真なら終了ステータスはゼロ、偽なら1、エラーが発生すれば2です。
-d
デバッグモードを有効にします。デーモンモードを無効にし、プロセスをフォアグラウンドに留め、入出力イベントを表示します。initスクリプトでは決して使ってはいけません。
-dA[file]
設定の読み込みが完了した直後に、起動時に検出したすべての依存関係をtar形式で指定ファイルにダンプします。“set-dumpable libs"と同等ですが、ライブラリをメモリに保持する代わりにファイルへダンプします。コアダンプの後、開発者がそのコアを解析できるように、必要なライブラリをすべて提供するために利用できます。すべてのOSで利用できるとは限りません。通常の設定ファイルとともに使うことを強く推奨します。また、手動実行時には必要に応じて”-c"を併用すると、haproxyは起動せず、ダンプ直後に終了します。例：
-dC[key]
設定ファイルをダンプします。各行をトークンに分割した後に行うため、コメントは除去され、インデントは強制的に整えられます。ゼロ以外のキーを指定すると、機密フィールドの手前で行を切り詰め、識別子とアドレスは、CLIの匿名化モードと同じアルゴリズムでこのキーを使ってハッシュ化して出力します。そのため、同じキーで匿名化したダンプの状況を調べるために必要とする開発者へ、安全に出力を共有できます。CLIの"set anon"コマンドも参照してください。
-dD
診断モードを有効にします。このモードでは、疑わしい設定文について追加の警告を出力します。“zero-warning"モードでは、一部の出力が起動を妨げます。
この診断は、人が潜在的な問題に気付くためのものです。その設定が完全に意図したものである場合もあります。診断内容は、安定ブランチ内でも、まったく同じ設定を実行するマシン間でも変わる可能性があります。そのため、有効な設定文も定期的に疑わしいと報告します。より詳しい診断を行うために、"-c"と組み合わせてだけ使用するべきです。その結果を、サービスの起動を妨げるために使ってはなりません（“zero-warning"または”-dW"と組み合わせると、そのようになります）。
-dF
データのfast-forwardを無効にします。これは、ストリームを起こさずに一方から他方へ直接データを渡すことで転送を最適化する仕組みです。このディレクティブで、この最適化を無効にできます。カーネルのTCP splicingもすべて無効になる点に注意してください。このコマンドは通常の利用を意図したものではなく、一般には複雑なデバッグ作業の中で開発者が提案する場合にだけ使用します。
-dG
ホスト名をアドレスに解決する際のgetaddrinfo()の使用を無効にします。getaddrinfo()が期待どおりに動作していない疑いがある場合に使えます。さまざまなシステムに誤ったgetaddrinfo()の実装が存在し、調査しにくい異常を引き起こすため、このオプションが用意されました。
-dI
安全でないforkを有効にします。globalセクションの"insecure-fork-wanted"と同等です。アドレスを解決するためにaddr2lineをforkする必要があるASANで、すべての回帰テストを実行するときに役立つ場合があります。
-dK<class[,class]*>
各クラスに登録されたキーワードの一覧をダンプします。クラスの一覧は”-dKhelp"で確認できます。"-dKall"ですべてのクラスをダンプするか、ヘルプに表示されたクラスの一部をカンマ区切りの一覧で指定できます。出力形式は、ダンプするキーワードのクラスによって異なります（たとえば、“cfg"は既知の設定キーワードを設定ファイルに似た形式で表示し、“smp"はサンプル取得関数の前に各ルールセットとの互換性マトリックスを付けて表示します）。人がそのまま利用することはあまりありませんが、特定の場所に新しいキーワードが追加されたことを検出し、文書、構文強調ファイル、設定パーサー、APIなどを自動更新する外部ツールには大いに役立ちます。出力形式は時間とともに多少変わる可能性があるため、主に過去のアーカイブとの差分検出に利用することを強く推奨します。各種キーワード登録サブシステムが作られるよりずっと前から存在するキーワードも多く、それらはここに現れないため、すべてのキーワードが一覧に含まれるわけではありません。ただし、新しいキーワードは現在の仕組みでのみ追加されるので、この出力を使って言語への追加を高い精度で検出できると考えてよいでしょう。動的に作られるキーワードもダンプできるように、設定を完全に解析した後でのみダンプします。ダンプして終了するには、既存の設定に対して静粛な設定チェックを実行するとよいでしょう。
設定ファイルがない場合でも、"-f /dev/null"を使えばデフォルトのキーワードをすべてダンプできます。ただし、リスナーが存在しないため終了ステータスはゼロにならず、無視する必要があります。
-dL
設定処理の終了時に読み込まれている動的共有ライブラリの一覧をダンプします。通常は、実行可能ファイル自身に加えて、たとえばLuaコードから読み込まれるものなど、間接的な依存関係も含みます。すべての依存関係のtarballを直接作成できるよう、容易に整形できる形式で一覧を出力します。プログラムの起動を停止しないため、読み込んだオブジェクトの一覧だけ（エラー時は何も表示しません）を出力する”-c"と”-q"の組み合わせでのみ使用することを推奨します。また、コアファイルの解析を支援するためにこのようなパッケージを提供する場合、多くのライブラリは実際にはシンボリックリンクであり、アーカイブ作成時にリンク先を取り込む必要があることを忘れないでください。
詳細モード（-V）で起動すると、静粛モード（-q）を使用していない限り、共有ライブラリのアドレス範囲も列挙します。
-dM[<byte>[,]][help|options,...]
メモリポイズニングを強制し、またはその他のメモリデバッグオプションを変更します。メモリポイズニングとは、malloc()またはpool_alloc()で割り当てるすべてのメモリ領域を、呼び出し元へ渡す前に<byte>で埋めることです。<byte>を指定しない場合、デフォルトは0x50（‘P’）です。動作は少し遅くなりますが、コードの初期化漏れによって不規則なクラッシュを引き起こす問題を、確実に再現するのに役立ちます。-dM0には、すべてのmalloc()をcalloc()に変える効果がある点に注意してください。このオプションを使って不具合が現れたり消えたりする場合は、いずれにしてもhaproxyにバグがあるため、報告してください。ほかにも、単独で、またはバイト値の後にカンマで区切って指定できるオプションがあります。特別なオプション"help"は、現在対応しているオプションと現在の値を一覧表示します。各デバッグオプションは、強制的に有効または無効にできます。通常はOSに応じた最適なオプションがビルド時に選ばれるため、開発者から提案されない限り調整する必要はありません。対応するデバッグオプションは次のとおりです（設定／解除）。
- fail / no-fail:
- no-merge / merge:
- cold-first / hot-first:
- integrity / no-integrity:
- backup / no-backup:
- no-global / global:
- no-cache / cache:
- caller / no-caller:
- tag / no-tag:
- poison / no-poison:
-dR
リッスンポートのSO_REUSEPORTソケットオプションを無効にします。“global"セクションの"noreuseport"キーワードと同等です。マルチスレッドの構成で、haproxyのスレッド間の負荷分散に問題が見られる場合（topで監視できます）に適用できます。
-dS
splice()システムコールの使用を無効にします。“global"セクションの"nosplice"キーワードと同等です。splice()の動作不良や性能問題が疑われる場合、またはstraceで転送データを確認する場合に使えます（splice()を使用すると、転送データは表示されません）。
-dT
ktlsの使用を無効にします。“global"セクションの"noktls"キーワードと同等です。主にktlsに関連するバグが疑われる場合に役立ちます。
-dV
サーバー側のSSL検証を無効にします。“global"セクションに"ssl-server-verify none"を設定するのと同等です。本番環境の問題を本番環境以外で再現する場合に便利です。サーバーとのSSL通信の安全性を低下させるため、initスクリプトでは決して使わないでください。
-dW
設定すると、設定ファイルの処理中に警告が一つでも出た場合、haproxyは起動を拒否します。微妙な誤りを検出し、設定を整理して、バージョン間での移植性を保つのに役立ちます。設定を人が管理する場合はサービススクリプトでこのオプションを設定することを推奨しますが、自動生成した設定は警告が多くなりがちなので、使用しないことを推奨します。"-c"と組み合わせると、チェック対象の設定に警告があれば失敗させられます。globalオプション"zero-warning"と同等です。
-dZ
“zero-copy"モードでのデータ転送を無効にします。“global"セクションの"tune.disable-zero-copy-forwarding"キーワードと同等です。データの欠落や整合性に問題がある場合に役立ちます。また、カーネルのTCP splicingもすべて無効にするため、straceで転送データを確認する場合にも役立ちます。
-db
バックグラウンドモードとマルチプロセスモードを無効にします。プロセスはフォアグラウンドに留まります。Ctrl-Cだけで停止できるため、主に開発中や小規模なテストで使います。initスクリプトでは決して使わないでください。
-dc
CPUアフィニティのデバッグを有効にします。起動前に、選択したCPUと除外したCPUの一覧、およびそれらのトポロジーを報告します。
-de
“epoll"ポーラーの使用を無効にします。“global"セクションの"noepoll"キーワードと同等です。主にこのポーラーに関連するバグが疑われる場合に役立ちます。epollに対応するシステムでは、通常、代わりに"poll"ポーラーを使います。
-dk
“kqueue"ポーラーの使用を無効にします。“global"セクションの"nokqueue"キーワードと同等です。主にこのポーラーに関連するバグが疑われる場合に役立ちます。kqueueに対応するシステムでは、通常、代わりに"poll"ポーラーを使います。
-dp
“poll"ポーラーの使用を無効にします。“global"セクションの"nopoll"キーワードと同等です。主にこのポーラーに関連するバグが疑われる場合に役立ちます。pollに対応するシステムでは、通常、代わりに"select"ポーラーを使います。selectは無効にできず、ファイル記述子数は1024に制限されます。
-dr
サーバーアドレスの解決失敗を無視します。本番環境の外で設定を検証すると、同じリゾルバーにアクセスできずにサーバーアドレスの解決が失敗し、設定をテストしにくくなることがよくあります。このオプションは、すべてのサーバーのアドレス解決方式の一覧の末尾に"none"を加えるだけです。これにより、libcでアドレスを解決できなくても、起動シーケンスを中断しません。
-dt [<trace_desc>,...]
stderrへのトレースを有効にします。引数がなければ、すべてのトレースソースをerrorレベルで有効にします。特に、クライアントやサーバーのプロトコル違反を検出する場合に役立ちます。任意の引数で、さまざまなトレース設定を’,‘区切りの一覧として指定できます。各要素は、一つまたはすべてのトレースソースを有効にします。また、各要素では、トレース名との内部区切りに’:‘を使い、レベルと詳細度を任意に指定できます。無効な詳細度名またはレベル名を入力すると、利用可能なキーワードの一覧を表示します。たとえば、各フィールドに’help’を渡して、先に一覧を確認すると便利です。
-dv
“evports"ポーラーの使用を無効にします。“global"セクションの"noevports"キーワードと同等です。主にこのポーラーに関連するバグが疑われる場合に役立ちます。イベントポートに対応するシステム（Solaris 10以降に由来するSunOS）では、通常、代わりに"poll"ポーラーを使います。
-m <limit>
プロセスのデータ保持に使う、割り当て可能なメモリを<limit>メガバイトに制限します。通常の動作に必要なメモリ量によっては、接続が拒否されたり、動作が遅くなったりする場合があります。主に、リソース消費が制限された状況でhaproxyプロセスを動かすために使います。メモリはhaproxyプロセス間で共有されず、fork()システムコールで作成した子プロセスは親のリソース制限を継承する点が重要です。そのため、マスターワーカーモードでは、このメモリ上限はマスターとforkされたワーカープロセスに個別に適用されます。
-n <limit>
プロセスごとの接続数の上限を<limit>に制限します。globalセクションの"maxconn"キーワードと同等で、このキーワードより優先されます。リソース制限が低すぎるシステムでサービス停止を避けるため、低い上限をすばやく強制する場合に使えます。
-p <file>
起動時に、すべてのプロセスのPIDを<file>へ書き込みます。“global"セクションの"pidfile"キーワードと同等です。ファイルは、"-C"によるchdir()の後、chroot jailに入る前に開きます。各PIDは一行ずつ記録されます。
-q
“quiet"モードを設定し、メッセージの出力を無効にします。"-c"と組み合わせ、設定ファイルが有効かどうかだけを確認するために使えます。
-S <bind>[,bind_options...]
マスターワーカーモードで、マスターCLIをバインドします。これにより、実行中または終了へ向かっているすべてのプロセスにアクセスできます。安全のため、マスターCLIはローカルのUNIXソケットにバインドすることを推奨します。バインドオプションは設定ファイルの"bind"キーワードと同じですが、語の区切りにはスペースの代わりにカンマを使います。
このソケットは、シームレスリロード時に古いプロセスからリッスンソケットを取得する用途には使えない点に注意してください。
-sf <pid>*
起動完了後、古いプロセスに"finish"シグナル（SIGUSR1）を送り、実行中の処理を終えてから終了するよう要求します。<pid>はシグナルを送るPIDの一覧です（一つの引数に一つ）。一覧は、”-“で始まるオプションで終わります。PIDの一覧が空でも問題ないため、“pidof"や"pgrep"などのコマンドの結果から、その場で組み立てられます。
-st <pid>*
起動完了後、古いプロセスに"terminate"シグナル（SIGTERM）を送り、実行中の処理を完了させず、直ちに終了させます。<pid>はシグナルを送るPIDの一覧です（一つの引数に一つ）。一覧は、”-“で始まるオプションで終わります。PIDの一覧が空でも問題ないため、“pidof"や"pgrep"などのコマンドの結果から、その場で組み立てられます。
-v
バージョンとビルド日を表示します。
-vv
バージョン、ビルドオプション、ライブラリのバージョン、利用可能なポーラーを表示します。バグ報告では、この出力が必ず求められます。
-x <unix_socket>
指定したソケットに接続し、古いプロセスからリッスンソケットを取得して、新しくバインドを試みる代わりにそれらを使います。Linuxで設定をリロードするときに、新しい接続を取りこぼさないようにするのに役立ちます。
マスターワーカーモードを使わない場合、設定内で"expose-fd listeners"を指定して、統計ソケットでこの機能を有効にしなければなりません。
マスターワーカーモードでは、“expose-fd listeners"は不要です。リロード時には、マスターが"sockpair@“構文でこのオプションを自動的に使います。これにより、設定で宣言した統計ソケットを使わずに、マスターがワーカーへ直接接続できます。これを無効にするには、-x /dev/nullを渡します。
initファイルから安全にHAProxyを起動するには、デーモンモードを強制し、既存のPIDをPIDファイルに保存し、そのファイルを使って、古いプロセスに処理を完了してから終了するよう通知します。
設定を用途別のいくつかのファイル（tcpとhttpなど）に分割している場合は、"-f"オプションの使用を推奨します。
顧客ごとのファイルなど、ファイル数があらかじめ分からない場合は、固定桁数の連番で始まる名前を付け、必要に応じてデフォルト設定を読み込んだ後、”–“で読み込むことを推奨します。
何らかの理由で起動に失敗することがあります。その場合、呼び出しているHAProxyが期待するバージョンであり、期待する機能（SSL、PCRE、圧縮、Luaなど）をサポートしているかを確認することが重要です。“haproxy -vv"で確認できます。一部のビルドオプション、対象システム、使用するライブラリのバージョンなど、重要な情報が表示されます。バグ報告を投稿するときにも、この情報が必ず求められます。
HAProxy version 1.6-dev7-a088d3-4 2015/10/08 Copyright 2000-2015 Willy Tarreau willy@haproxy.org
Build options:
Default settings:
Encrypted password support via crypt(3): yes Built with zlib version: 1.2.6 Compression algorithms supported: identity(“identity”), deflate(“deflate”), \ raw-deflate(“deflate”), gzip(“gzip”) Built with OpenSSL version: OpenSSL 1.0.1o 12 Jun 2015 Running on OpenSSL version: OpenSSL 1.0.1o 12 Jun 2015 OpenSSL library supports TLS extensions: yes OpenSSL library supports SNI: yes OpenSSL library supports prefer-server-ciphers: yes Built with PCRE version: 8.12 2011-01-15 PCRE library supports JIT: no (USE_PCRE_JIT not set) Built with Lua version: Lua 5.3.1 Built with transparent proxy support using: IP_TRANSPARENT IP_FREEBIND
Available polling systems:
Total: 3 (3 usable), will use epoll.
開発者ではない多くのユーザーも、ここで次の関連情報を確認できます。
- バージョン
上の1.6-dev7-a088d3-4は、現在のコードがコミットID “a088d3"であり、正式版"1.6-dev7"から4番目のコミットであることを意味します。バージョン1.6-dev7は"1.6-dev7-8c1ad7"のように表示されます。ここで実際に重要なのは"1.6-dev7"です。これは、将来バージョン1.6となるものの7番目の開発版です。開発版は、何をしているかを正確に理解している場合を除き、本番環境での使用には適しません。安定版は"1.5.14-16f863"のように3つの数値からなるバージョンで表示され、バージョン1.5に対する14番目の修正リリースを意味します。こちらは本番で使用できるバージョンです。
- リリース日
2015/10/08。世界共通の年／月／日の形式で表します。ここでは2015年10月8日を意味します。安定版リリースは数か月ごと（当初は1〜2か月、製品が非常に安定した後は6か月になる場合もあります）に発行されるため、ここに古い日付が表示される場合は、その後修正されたバグやセキュリティ問題の影響を受けている可能性があり、公式サイトを確認する価値があります。
- ビルドオプション
自分でパッケージをビルドする人に関係する情報で、期待どおりに動かない理由を説明できる場合があります。たとえば、上の開発版はLinux 2.6.28以降向けにビルドされ、汎用CPUを対象としており（CPU固有の最適化なし）、コードの最適化もまったく行っていない（-O0）ため、性能は低くなります。
- ライブラリのバージョン
zlibのバージョンは、ライブラリ自体から得たものを表示します。一般にzlibは非常に安定した製品と考えられており、アップグレードが必要になることはほとんどありません。OpenSSLは、ビルド時に使ったバージョンと、現在システム上で使っているバージョンの二つを表示します。末尾の文字は異なる場合がありますが、数値は決して異なりません。OpenSSLのバグの大半はセキュリティ問題で、真剣に対処する必要があるため、ビルド日も表示します。このライブラリは必ず最新の状態に保たなければなりません。ここで4か月前のバージョンが表示されるのは非常に疑わしく、実際に更新を見逃しています。PCREは非常に高速な正規表現を提供するため、強く推奨します。JITなど一部の拡張はすべてのバージョンにあるわけではなく、まだ新しいため、それらを含めずにビルドすることを好む人もいます。そのため、ビルド時の状態も表示します。Luaスクリプト言語については、HAProxyはバージョン5.3を想定しています。HAProxy 1.6の少し前にリリースされたばかりなので、まだ非常に新しいバージョンです。このブランチ向けの修正が出ていないか、LuaのWebサイトを確認することが重要です。
- 利用可能なポーリング方式は、次の場合にプロセスの拡張性に影響します
同時接続数が約千を超える場合です。これらの方式は、ビルド時にTARGET変数へ正しいシステムを指定した場合にのみ利用できます。Linuxでは"epoll"方式、BSDではkqueue方式を強く推奨します。これらがなければpoll()、場合によってはselect()を使うことになり、多数の接続を処理するとCPU使用率が高くなります。