環境辞書、 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ドキュメントをご覧ください。

共有された状態としての環境

前述のとおり、 env オブジェクトは単純な辞書サブクラスで、自分のfabfileコードにも保管することができます。これは単一の実行内に複数のタスク間で状態を保持するのに便利なことが有ります。

注釈

env のこの側面は多分に歴史的なものです。以前は、fabfileは純粋なPythonではありませんでしたので、この「環境」がタスク間でやりとりするための唯一の方法でした。現在では、他のタスクやサブルーチンをダイレクトに呼び出すことができ、必要ならモジュールレベルでの共有された状態を保持することさえできます。

将来のバージョンでは、Fabricはスレッドセーフになり、その時点で env はグローバルな状態を保持する唯一の簡単で安全な方法になるでしょう。

その他の留意事項

これは dict のサブクラスである一方、Fabricの env は変更されていて、これまでの例等のいくつかに見られるよう、属性アクセスの方法でその値を読み書きできます。言い換えると、 env.host_stringenv['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 オプションと引数 をご覧ください。クロスリファレンスが適宜提供されています。

参考

--set

abort_exception

デフォルト: None

Fabricは通常は、標準エラー出力にエラーメッセージを表示し``sys.exit(1)`` を呼び出すことによって中止を扱います。この設定により、この挙動( env.abort_exceptionNone の時に起こること)をオーバーライドできます。

文字列(表示されるであろうエラーメッセージ)を取り、例外インスタンスを返す呼び出し可能なものを与えます。 SystemExit ( sys.exit が行うこと)の代わりにこの例外オブジェクトが引き起こされます。

大抵の場合、上記説明(呼び出し可能で、文字列を取り、例外インスタンスを返す)に完全に合わせるように、単にこれを例外クラスにセットするとよいでしょう。例えば、 env.abort_exception = MyExceptionClass です。

abort_on_prompts

デフォルト: False

True の時、Fabricは非インタラクティブモードで動作し、いつでも abort を呼び出すとユーザーに入力を促すプロンプトを表示します(パスワードの入力プロンプト、"どのホストに接続しますか?" プロンプト、 prompt のfabfile実行などなど)。これにより、予期せぬ状況が発生した時にユーザーの入力を永遠にブロックする代わりに、ユーザーはFabricのセッションを常にきれいに終了させることができます。

バージョン 1.1 で追加.

all_hosts

デフォルト: []

実行しているコマンドのために全ホストのリストが fab によって設定されます。情報目的のみです。

always_use_pty

デフォルト: True

False にセットされると run/sudopty=False 付きで呼び出された時のように振る舞います。

参考

--no-pty

バージョン 1.0 で追加.

colorize_errors

デフォルト False

True にセットされると、見分けやすいようにターミナルへのエラー出力を赤で、警告をマジェンタで表示します。

バージョン 1.7 で追加.

combine_stderr

デフォルト: True

SSH層でリモートプログラムの標準出力と標準エラー出力のストリームをマージして、表示するときに見難くならないようにします。これが必要な理由とその効果についての詳細はを 標準出力と標準エラー出力の結合 ご覧ください。

バージョン 1.0 で追加.

command

デフォルト: None

fab によって実行中のコマンド名がセットされます(例えば、 $ fab task1 task2 として実行された場合、 env.commandtask1 の 実行中は "task1" にセットされ、次に "task2" にセットされます)。情報目的のみです。

command_prefixes

デフォルト: []

prefix によって変更され、 run/sudo によって実行されるコマンドの先頭に追加されます。

バージョン 1.0 で追加.

command_timeout

デフォルト: None

リモートコマンドのタイムアウト、秒で指定。

バージョン 1.6 で追加.

connection_attempts

デフォルト: 1

新しいサーバーに接続するときにFabricが接続を試行する回数です。後方互換性のため、デフォルトでは1回だけの試行になっています。

バージョン 1.4 で追加.

cwd

デフォルト: ''

カレントのワーキングディレクトリ。cd コンテキストマネージャ用に状態保持のために利用されます。

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 は実行の最後ではなく各個別のタスク実行後に接続を切ります。これにより、一般的な未使用セッションのパイルアップや、プロセスごとに開けるファイル制限やネットワークのハードウェアに伴う問題の発生を避けることができます。

注釈

アクティブの場合、この設定は、最後ではなく出力全体を通して接続解除のメッセージを表示します。将来のリリースでは改善されるかもしれません。

effective_roles

デフォルト: []

実行中のコマンドのロールのリストが fab によって設定されます。情報目的のみです。

バージョン 1.9 で追加.

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 で追加.

参考

--gateway

host_string

デフォルト: None

runput などの実行時にFabricが接続するカレントのユーザー/ホスト/ポートを定義します。前回セットされたホストリストを順に処理するときに fab によってセットされます。また、Fabricをライブラリとして使用するときに手動でセットすることもできます。

forward_agent

デフォルト: False

True にセットされると、ローカルのSSHエージェントをリモート側に転送できるようになります。

バージョン 1.4 で追加.

host

デフォルト: None

fab によって env.host_string のホスト名部分にセットされます。情報目的のみです。

hosts

デフォルト: []

タスクごとのホストリストの作成時に利用されるグローバルなホストリストです。

keepalive

デフォルト: 0 (例: keepalive無し)

SSHのキープアライブ間隔に使用するために指定する整数値です。基本的にSSHのコンフィグオプションの ClientAliveInterval にマップされます。ネットワークハードウェアの問題等により接続がタイムアウトするときに便利です。

参考

--keepalive

バージョン 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_agent

デフォルト: False

True にすると、鍵ベースの認証時にSSH層が動作中のSSHエージェントを探さないようにします。

バージョン 0.9.1 で追加.

参考

--no_agent

no_keys

デフォルト: False

True にすると、SSH層が $HOME/.ssh/ フォルダーから秘密鍵ファイルを読み込まないようにします(もちろん、 fab -i 経由で明示的に読み込まれた鍵ファイルは利用されます)。

バージョン 0.9.1 で追加.

参考

-k

parallel

デフォルト: False

True の時、強制的にすべてのタスクを並列に実行します。 env.linewise に影響します。

バージョン 1.3 で追加.

password

デフォルト: None

リモートホスト接続時および/もしくは sudo のプロンプトの答える時にSSH層が使うデフォルトのパスワードです。

passwords

デフォルト: {}

この辞書は主に内部で利用され、ホスト文字列ごとのパスワードキャッシュとして自動的に埋められます。キーは完全な ホスト文字列 で、値はパスワード(文字列)です。

警告

この辞書を手動で修正もしくは生成したのなら、ユーザーとポートの値をともなった 条件を完全に満たしたホストストリングを使用しなくてはなりません。ホストストリングAPIについての詳細は上のリンクを参照してください。

バージョン 1.0 で追加.

path

デフォルト: ''

run/sudo/local のコマンド実行時の $PATH シェル環境変数のセットに利用されます。この値の管理には、直接のセットではなく path コンテキストマネージャの利用をおすすめします。

バージョン 1.0 で追加.

pool_size

デフォルト: 0

タスクの並列実行時に利用する並列プロセスの数をセットします。

バージョン 1.3 で追加.

prompts

デフォルト: {}

prompts 辞書はユーザーが対話式のプロンプトをコントロールできるようにします。この辞書内のキーがコマンドの標準出力ストリーム内に見つかれば、Fabricは自動的に対応する辞書の値を応答します。

バージョン 1.9 で追加.

port

デフォルト: None

ホストリストを順次処理するときに fab によって env.host_string のポート部分にセットされます。デフォルトポートを指定するときにお利用されます。

real_fabfile

デフォルト: None

読み込んだfabfileへのパスが fab によってセットされます。情報取得のみです。

remote_interrupt

デフォルト: None

Ctrl-Cがリモートでの中断をもたらすかローカルでのキャプチャにするかをコントロールします。設定は:

  • None (デフォルト): open_shell がリモートの割り込み挙動を表示するだけで、 run/sudo がローカルの割り込みをキャプチャします。
  • False: open_shell がローカルでキャプチャします。
  • True: すべての機能が割り込みをリモート側に送ります。

バージョン 1.6 で追加.

rcfile

デフォルト: $HOME/.fabricrc

Fabricのローカルの設定ファイル読み込み時に利用されるパスです。

reject_unknown_hosts

デフォルト: False

True の場合、ユーザーの既知のホストファイルに載っていないホストへの接続時にSSH層が例外を発生させます。

system_known_hosts

デフォルト: None

セットするには、 known_hosts ファイルへのパスをセットします。SSH層はユーザーの既知のホストファイルを読む前にこのファイルを読みます。

参考

SSHの動作

roledefs

デフォルト: {}

ホストリストへマッピングするロールを定義する辞書です。

roles

デフォルト: []

タスクごとのホストリスト作成時に使用されるグローバルなロースリストです。

shell

デフォルト: /bin/bash -l -c

例えば run などとともにコマンドを実行する時のシェルラッパーに使われる値です。 <env.shell> "<command goes here>" 形式で存在する必要があります。例えば、デフォルトで使用するBashの -c オプション(その値をコマンド文字列として扱う)です。

参考

--shell, FAQ - デフォルトシェルとしてのbash, 実行モデル

skip_bad_hosts

デフォルト: False

True の時、 fab (もしくは execute を使った fab 以外の利用) が接続できないホストをスキップします。

バージョン 1.4 で追加.

skip_unknown_tasks

デフォルト: False

True の時、 fab (もしくは execute を使った fab 以外の利用) が見つからなかったタスクを中止せずにスキップします。

ssh_config_path

デフォルト: $HOME/.ssh/config

代替のSSH設定ファイルパスの指定できます。

バージョン 1.4 で追加.

ok_ret_codes

デフォルト: [0]

このリストのリターンコードが run/sudo/sudo への呼び出しを成功したとみなすか否かを決定するために利用されます。

バージョン 1.6 で追加.

sudo_prefix

デフォルト: "sudo -S -p '%(sudo_prompt)s' " % env

sudo 呼び出しのコマンド文字列の先頭に追加された実際の sudo コマンド。デフォルトのリモート $PATHsudo 権限を持っていないユーザーやその他の変更(パスワード無し sudo 実施時に -p を取り除いたり)を必要とするユーザーにとってはこの変更は便利です。

参考

sudo オペレーション; env.sudo_prompt

sudo_prompt

デフォルト: "sudo password:"

リモートシステム上の sudo プログラムに渡されることにより、Fabricがそのパスワードプロンプトを正しく認識できます。

参考

sudo オペレーション; env.sudo_prefix

sudo_user

デフォルト: None

sudouser 値が与えられたなった時のフォールバック値として使われます。settings との組み合わせが便利です。

参考

sudo

tasks

デフォルト: []

fab によって、実行中のコマンドのために実行すべきタスクの完全な一覧がセットされます。情報取得目的のみです。

timeout

デフォルト: 10

ネットワーク接続のタイムアウトを秒で。

バージョン 1.4 で追加.

use_shell

デフォルト: True

run/sudo への shell 引数のように振る舞うグローバルな設定です。False にセットされるとオペレーションは env.shell 内の実行されたコマンドをラップしません。

use_ssh_config

デフォルト: False

True にセットすると、FabricはローカルのSSHコンフィグファイルを読み込みます。

バージョン 1.4 で追加.

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変数に分けられると思います。

version

デフォルト: Fabricの現行バージョン文字列

主に情報取得が目的です。変更は、おそらく何も壊さないですがおすすめしません。

参考

--version

warn_only

デフォルト: False

run/sudo/local がエラー状態に遭遇した時に中止の代わりに警告を発するかどうかを指定します。