環境辞書、 env
¶
Fabricのシンプルだけれども不可欠な側面は "(環境)environment" として知られているものです。これはPythonの辞書サブクラスで、設定レジストリの組み合わせとして利用され、タスク間のデータ空間で共有されます。
この環境辞書はグローバルなシングルトン、 fabric.state.env
として現在は実装されていて、便利なように fabric.api
内に含まれています。 env
のキーは "env variables(環境変数)" として言及さることがあります。
設定としての環境¶
Fabricのほとんどの挙動は env
変数、例えば チュートリアル で見られる env.hosts
などを変更することによってコントロールされます。よく変更されて利用される env
変数は以下のものがあります:
user
: SSH接続を実行するときのFabricのデフォルトの値はご自分のローカルユーザー名で、必要ならenv.user
を使ってオーバーライドできます。また、ドキュメントの 実行モデル にはホストごとにユーザー名を指定するための情報が記載されています。password
: 必要に応じてデフォルト接続やsudoのパスワードを設定するために使用します。Fabricは、この値が設定されていない場合や正しくない場合に必要になった時にプロンプトを表示します。warn_only
: リモート側でエラーを検知したときにFabricが終了するかどうかを決めるブール設定です。この挙動に関する詳細は 実行モデル をご覧ください。
他にもたくさんの env 変数が有ります。完全な一覧はこのドキュメントの下、 env変数の全リスト をご覧ください。
settings
のコンテキストマネージャー¶
多くのケースで、一時的に env
変数の変更ができて、与えられる設定変更があるコードブロックだけに適用される方が便利なことあります。Fabricは settings
コンテキストマネージャを提供しています。これは任意の数のキー/バリューのペアを取ることができ、それでラップされたブロック内の env
を変更するのに利用できます。
例えば、 warn_only
(下を参照)設定が便利な状況はたくさんあると思います。これを何行かのコードに適用するには contrib
exists
関数にあるように、 settings(warn_only=True)
を使います。:
from fabric.api import settings, run
def exists(path):
with settings(warn_only=True):
return run('test -e %s' % path)
settings
とその他類似のツールに関する詳細は コンテキストマネージャー APIドキュメントをご覧ください。
その他の留意事項¶
これは dict
のサブクラスである一方、Fabricの env
は変更されていて、これまでの例等のいくつかに見られるよう、属性アクセスの方法でその値を読み書きできます。言い換えると、 env.host_string
と env['host_string']
は機能的に同一です。属性アクセスはタイピングを少しだけですが節約できることがよくありますし、コードをより読みやすくします。なので、 env
とのやりとりにはこの方法をおすすめします。
これが辞書であるということは、Pythonの 辞書
ベースの文字列挿入などの他の場合に有益になりえます。これは特に、単一の文字列に複数の env 変数を挿入する必要があるときにとても便利です。"通常の" 文字列挿入の利用は次のようなものです:
print("Executing on %s as %s" % (env.host, env.user))
辞書スタイルの挿入を利用するとより読みやすく、少しだけ短くなります:
print("Executing on %(host)s as %(user)s" % env)
env変数の全リスト¶
以下は定義済みの(もしくは実行中にFabric自身によって定義される)すべての環境変数のリストです。この内の多くは直接操作できますが、通常は settings
経由もしくは cd
などの特定のコンテキストマネージャ経由で context_managers
を使うほうが多くの場合はベストでしょう。
これらの多くが fab
のコマンドラインスイッチ経由で設定可能であることに留意してください。このコマンドラインスイッチの詳細は fab オプションと引数 をご覧ください。クロスリファレンスが適宜提供されています。
参考
abort_exception
¶
デフォルト: None
Fabricは通常は、標準エラー出力にエラーメッセージを表示し``sys.exit(1)`` を呼び出すことによって中止を扱います。この設定により、この挙動( env.abort_exception
が None
の時に起こること)をオーバーライドできます。
文字列(表示されるであろうエラーメッセージ)を取り、例外インスタンスを返す呼び出し可能なものを与えます。 SystemExit
( sys.exit
が行うこと)の代わりにこの例外オブジェクトが引き起こされます。
大抵の場合、上記説明(呼び出し可能で、文字列を取り、例外インスタンスを返す)に完全に合わせるように、単にこれを例外クラスにセットするとよいでしょう。例えば、 env.abort_exception = MyExceptionClass
です。
abort_on_prompts
¶
デフォルト: False
True
の時、Fabricは非インタラクティブモードで動作し、いつでも abort
を呼び出すとユーザーに入力を促すプロンプトを表示します(パスワードの入力プロンプト、"どのホストに接続しますか?" プロンプト、 prompt
のfabfile実行などなど)。これにより、予期せぬ状況が発生した時にユーザーの入力を永遠にブロックする代わりに、ユーザーはFabricのセッションを常にきれいに終了させることができます。
バージョン 1.1 で追加.
always_use_pty
¶
デフォルト: True
False
にセットされると run
/sudo
が pty=False
付きで呼び出された時のように振る舞います。
参考
バージョン 1.0 で追加.
combine_stderr
¶
デフォルト: True
SSH層でリモートプログラムの標準出力と標準エラー出力のストリームをマージして、表示するときに見難くならないようにします。これが必要な理由とその効果についての詳細はを 標準出力と標準エラー出力の結合 ご覧ください。
バージョン 1.0 で追加.
command
¶
デフォルト: None
fab
によって実行中のコマンド名がセットされます(例えば、 $ fab task1 task2
として実行された場合、 env.command
は task1
の 実行中は "task1"
にセットされ、次に "task2"
にセットされます)。情報目的のみです。
参考
connection_attempts
¶
デフォルト: 1
新しいサーバーに接続するときにFabricが接続を試行する回数です。後方互換性のため、デフォルトでは1回だけの試行になっています。
バージョン 1.4 で追加.
dedupe_hosts
¶
デフォルト: True
マージされたホストリストで重複を取り除きます。そのため、与えられたすべてのホスト文字列は1度しか使用されません(例えば、 @hosts
+ @roles
もしくは -H
と -R
の組み合わせ使用時)。
False
にセットされると、このオプションは重複を排除しなくなります。そうすると、明示的に同一ホストに対して一つのタスクを複数回実行したい場合(例えば、シリアルに動作するけれども並列で実行させたい場合)に、そのように実行できるようになります。
バージョン 1.5 で追加.
disable_known_hosts
¶
デフォルト: False
True
の場合、SSH層はユーザーのknown-hostsファイルの読み込みをスキップします。ホストキーが実際には有効なのに "既知のホスト" が変わった場合(例えば、EC2などのクラウドサーバなど)に発生する例外を避けるのに便利です。
eagerly_disconnect
¶
デフォルト: False
True
にすると fab
は実行の最後ではなく各個別のタスク実行後に接続を切ります。これにより、一般的な未使用セッションのパイルアップや、プロセスごとに開けるファイル制限やネットワークのハードウェアに伴う問題の発生を避けることができます。
注釈
アクティブの場合、この設定は、最後ではなく出力全体を通して接続解除のメッセージを表示します。将来のリリースでは改善されるかもしれません。
exclude_hosts
¶
デフォルト: []
fab
実行中に スキップする ホスト文字列のリストを指定します。通常は --exclude-hosts/-x
経由でセットされます。
バージョン 1.1 で追加.
fabfile
¶
デフォルト: fabfile.py
fab
がfabfileを読み込むときに探すファイル名パターンです。特定のファイルを指定するにはそのファイルへのフルパスを用います。これをfabfile内に指定するのはもちろん意味がありませんが、 .fabricrc
内やコマンドライン上で指定することができます。
gateway
¶
デフォルト: None
指示されたホストを通したSSHドリブンなゲートウェイ接続を可能にします。値は env.host_string で用いられるような通常のFabricのホスト文字列でなければいけません。この値がセットされると、新規に作成される接続はそのリモートSSHデーモンを通してSSHのトラフィックが最終目的地に送られるようにセットされます。
バージョン 1.5 で追加.
参考
host_string
¶
デフォルト: None
run
、 put
などの実行時にFabricが接続するカレントのユーザー/ホスト/ポートを定義します。前回セットされたホストリストを順に処理するときに fab
によってセットされます。また、Fabricをライブラリとして使用するときに手動でセットすることもできます。
参考
keepalive
¶
デフォルト: 0
(例: keepalive無し)
SSHのキープアライブ間隔に使用するために指定する整数値です。基本的にSSHのコンフィグオプションの ClientAliveInterval
にマップされます。ネットワークハードウェアの問題等により接続がタイムアウトするときに便利です。
参考
バージョン 1.1 で追加.
key
¶
デフォルト: None
接続認証中に使用されるSSHキーを含む文字列もしくはファイル等のオブジェクトです。
注釈
SSHキーを利用するためのもっとも一般的な方法は key_filename をセットすることです。
バージョン 1.7 で追加.
key_filename
¶
デフォルト: None
接続試行時のSSHキーファイルへのファイルパスを参照する文字列もしくは文字列のリストです。SSH層に直接渡されます。 -i
でセット/追加できます。
linewise
¶
デフォルト: False
一般的には並列モード実行時に、文字/バイトごとではなく行ごとにバッファするようにします。 --linewise
経由で有効化できます。このオプションは env.parallel によって暗黙に定義されます。 linewise
がFalseでも parallel
がTrueならlinewiseの挙動をとります。
バージョン 1.3 で追加.
local_user
¶
ローカルのシステムユーザー名を含む読み込み専用の値です。これは user の初期値と同じ値ですが、 user はCLI引数、Pythonのコードもしくは特定のホスト文字列によって変更可能で、local_user は常に同じ値を含みます。
no_keys
¶
デフォルト: False
True
にすると、SSH層が $HOME/.ssh/
フォルダーから秘密鍵ファイルを読み込まないようにします(もちろん、 fab -i
経由で明示的に読み込まれた鍵ファイルは利用されます)。
バージョン 0.9.1 で追加.
参考
passwords
¶
デフォルト: {}
この辞書は主に内部で利用され、ホスト文字列ごとのパスワードキャッシュとして自動的に埋められます。キーは完全な ホスト文字列 で、値はパスワード(文字列)です。
警告
この辞書を手動で修正もしくは生成したのなら、ユーザーとポートの値をともなった 条件を完全に満たしたホストストリングを使用しなくてはなりません。ホストストリングAPIについての詳細は上のリンクを参照してください。
参考
バージョン 1.0 で追加.
path
¶
デフォルト: ''
run
/sudo
/local
のコマンド実行時の $PATH
シェル環境変数のセットに利用されます。この値の管理には、直接のセットではなく path
コンテキストマネージャの利用をおすすめします。
バージョン 1.0 で追加.
prompts
¶
デフォルト: {}
prompts
辞書はユーザーが対話式のプロンプトをコントロールできるようにします。この辞書内のキーがコマンドの標準出力ストリーム内に見つかれば、Fabricは自動的に対応する辞書の値を応答します。
バージョン 1.9 で追加.
remote_interrupt
¶
デフォルト: None
Ctrl-Cがリモートでの中断をもたらすかローカルでのキャプチャにするかをコントロールします。設定は:
None
(デフォルト):open_shell
がリモートの割り込み挙動を表示するだけで、run
/sudo
がローカルの割り込みをキャプチャします。False
:open_shell
がローカルでキャプチャします。True
: すべての機能が割り込みをリモート側に送ります。
バージョン 1.6 で追加.
system_known_hosts
¶
デフォルト: None
セットするには、 known_hosts
ファイルへのパスをセットします。SSH層はユーザーの既知のホストファイルを読む前にこのファイルを読みます。
参考
shell
¶
デフォルト: /bin/bash -l -c
例えば run
などとともにコマンドを実行する時のシェルラッパーに使われる値です。 <env.shell> "<command goes here>"
形式で存在する必要があります。例えば、デフォルトで使用するBashの -c
オプション(その値をコマンド文字列として扱う)です。
skip_bad_hosts
¶
デフォルト: False
True
の時、 fab
(もしくは execute
を使った fab
以外の利用) が接続できないホストをスキップします。
バージョン 1.4 で追加.
skip_unknown_tasks
¶
デフォルト: False
True
の時、 fab
(もしくは execute
を使った fab
以外の利用) が見つからなかったタスクを中止せずにスキップします。
ok_ret_codes
¶
デフォルト: [0]
このリストのリターンコードが run
/sudo
/sudo
への呼び出しを成功したとみなすか否かを決定するために利用されます。
バージョン 1.6 で追加.
sudo_prefix
¶
デフォルト: "sudo -S -p '%(sudo_prompt)s' " % env
sudo
呼び出しのコマンド文字列の先頭に追加された実際の sudo
コマンド。デフォルトのリモート $PATH
の sudo
権限を持っていないユーザーやその他の変更(パスワード無し sudo 実施時に -p
を取り除いたり)を必要とするユーザーにとってはこの変更は便利です。
参考
sudo
オペレーション; env.sudo_prompt
sudo_prompt
¶
デフォルト: "sudo password:"
リモートシステム上の sudo
プログラムに渡されることにより、Fabricがそのパスワードプロンプトを正しく認識できます。
参考
sudo
オペレーション; env.sudo_prefix
use_shell
¶
デフォルト: True
run
/sudo
への shell
引数のように振る舞うグローバルな設定です。False
にセットされるとオペレーションは env.shell
内の実行されたコマンドをラップしません。
user
¶
デフォルト: ユーザーのローカルユーザー名
リモートホスト接続時にSSH層によって利用されるユーザー名です。グローバルにセットすることも可能で、ホスト文字列に明示的にセットされていない場合にも利用されます。しかし、そのように明示された場合、この変数は一時的に現行値で上書きされます。例えば、その時に接続されているユーザーとして常に表示されます。
これを説明するには、次のfabfileを:
from fabric.api import env, run
env.user = 'implicit_user'
env.hosts = ['host1', 'explicit_user@host2', 'host3']
def print_user():
with hide('running'):
run('echo "%(user)s"' % env)
そしてこれを実行してみます:
$ fab print_user
[host1] out: implicit_user
[explicit_user@host2] out: explicit_user
[host3] out: implicit_user
Done.
Disconnecting from host1... done.
Disconnecting from host2... done.
Disconnecting from host3... done.
ご覧のとおり、host2
に対して実行中は env.user
は "explicit_user"
にセットされましたが、その後、前の値 ("implicit_user"
) に戻されています。
注釈
env.user
はいまのところ少し紛らわしい(設定**および**情報取得目的に用いられるので)ので、将来的には変更されると考えてください。情報取得の部分は別のenv変数に分けられると思います。