環境辞書、 `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_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 オプションと引数をご覧ください。クロスリファレンスが適宜提供されています。

参考

--set

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

参考

--abort-on-prompts

`all_hosts`¶

デフォルト: []

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

参考

実行モデル

`always_use_pty`¶

デフォルト: True

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

参考

--no-pty

バージョン 1.0 で追加.

`colorize_errors`¶

デフォルト False

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

バージョン 1.7 で追加.

`combine_stderr`¶

デフォルト: True

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

バージョン 1.0 で追加.

`command`¶

デフォルト: None

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

参考

実行モデル

`command_prefixes`¶

デフォルト: []

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

バージョン 1.0 で追加.

`command_timeout`¶

デフォルト: None

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

バージョン 1.6 で追加.

参考

--command-timeout

`connection_attempts`¶

デフォルト: 1

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

バージョン 1.4 で追加.

参考

--connection-attempts, timeout

`cwd`¶

デフォルト: ''

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

`dedupe_hosts`¶

デフォルト: True

マージされたホストリストで重複を取り除きます。そのため、与えられたすべてのホスト文字列は1度しか使用されません(例えば、 @hosts + @roles もしくは -H と -R の組み合わせ使用時)。

False にセットされると、このオプションは重複を排除しなくなります。そうすると、明示的に同一ホストに対して一つのタスクを複数回実行したい場合(例えば、シリアルに動作するけれども並列で実行させたい場合)に、そのように実行できるようになります。

バージョン 1.5 で追加.

`disable_known_hosts`¶

デフォルト: False

True の場合、SSH層はユーザーのknown-hostsファイルの読み込みをスキップします。ホストキーが実際には有効なのに "既知のホスト" が変わった場合(例えば、EC2などのクラウドサーバなど)に発生する例外を避けるのに便利です。

参考

--disable-known-hosts, SSHの動作

`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 内やコマンドライン上で指定することができます。

参考

--fabfile, fab オプションと引数

`gateway`¶

デフォルト: None

指示されたホストを通したSSHドリブンなゲートウェイ接続を可能にします。値は env.host_string で用いられるような通常のFabricのホスト文字列でなければいけません。この値がセットされると、新規に作成される接続はそのリモートSSHデーモンを通してSSHのトラフィックが最終目的地に送られるようにセットされます。

バージョン 1.5 で追加.

参考

--gateway

`host_string`¶

デフォルト: None

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

参考

実行モデル

`forward_agent`¶

デフォルト: False

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

バージョン 1.4 で追加.

参考

--forward-agent

`host`¶

デフォルト: None

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

`hosts`¶

デフォルト: []

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

参考

--hosts, 実行モデル

`keepalive`¶

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

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

参考

--keepalive

バージョン 1.1 で追加.

`key`¶

デフォルト: None

接続認証中に使用されるSSHキーを含む文字列もしくはファイル等のオブジェクトです。

注釈

SSHキーを利用するためのもっとも一般的な方法は key_filename をセットすることです。

バージョン 1.7 で追加.

`key_filename`¶

デフォルト: None

接続試行時のSSHキーファイルへのファイルパスを参照する文字列もしくは文字列のリストです。SSH層に直接渡されます。 -i でセット/追加できます。

参考

SSHClient.connect()に関するParamikoのドキュメント

`linewise`¶

デフォルト: False

一般的には並列モード実行時に、文字/バイトごとではなく行ごとにバッファするようにします。 --linewise 経由で有効化できます。このオプションは env.parallel によって暗黙に定義されます。 linewise がFalseでも parallel がTrueならlinewiseの挙動をとります。

参考

出力行単位対バイト単位 (Linewise vs bytewise)

バージョン 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 で追加.

参考

--parallel, 並列実行

`password`¶

デフォルト: None

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

参考

--initial-password-prompt, env.passwords, パスワード管理

`passwords`¶

デフォルト: {}

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

警告

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

参考

パスワード管理

バージョン 1.0 で追加.

`path`¶

デフォルト: ''

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

バージョン 1.0 で追加.

`pool_size`¶

デフォルト: 0

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

バージョン 1.3 で追加.

参考

--pool-size, 並列実行

`prompts`¶

デフォルト: {}

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

バージョン 1.9 で追加.

`port`¶

デフォルト: None

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

`real_fabfile`¶

デフォルト: None

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

参考

fab オプションと引数

`remote_interrupt`¶

デフォルト: None

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

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

バージョン 1.6 で追加.

`rcfile`¶

デフォルト: $HOME/.fabricrc

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

参考

--config, fab オプションと引数

`reject_unknown_hosts`¶

デフォルト: False

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

参考

--reject-unknown-hosts, SSHの動作

`system_known_hosts`¶

デフォルト: None

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

参考

SSHの動作

`roledefs`¶

デフォルト: {}

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

参考

実行モデル

`roles`¶

デフォルト: []

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

参考

--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-bad-hosts, 特定のホストの除外, 実行モデル

`skip_unknown_tasks`¶

デフォルト: False

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

参考

--skip-unknown-tasks

`ssh_config_path`¶

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

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

バージョン 1.4 で追加.

参考

--ssh-config-path, ネイティブのSSH configファイルの活用

`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

`sudo_user`¶

デフォルト: None

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

参考

sudo

`tasks`¶

デフォルト: []

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

参考

実行モデル

`timeout`¶

デフォルト: 10

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

バージョン 1.4 で追加.

参考

--timeout, connection_attempts

`use_shell`¶

デフォルト: True

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

`use_ssh_config`¶

デフォルト: False

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

バージョン 1.4 で追加.

参考

ネイティブのSSH configファイルの活用

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

参考

実行モデル, --user

`version`¶

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

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

参考

--version

`warn_only`¶

デフォルト: False

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

参考

--warn-only, 実行モデル

注意!!!!

環境辞書、 env¶

設定としての環境¶

settings のコンテキストマネージャー¶

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

その他の留意事項¶

env変数の全リスト¶

abort_exception¶

abort_on_prompts¶

all_hosts¶

always_use_pty¶

colorize_errors¶

combine_stderr¶

command¶

command_prefixes¶

command_timeout¶

connection_attempts¶

cwd¶

dedupe_hosts¶

disable_known_hosts¶

eagerly_disconnect¶

effective_roles¶

exclude_hosts¶

fabfile¶

gateway¶

host_string¶

forward_agent¶

host¶

hosts¶

keepalive¶

key¶

key_filename¶

linewise¶

local_user¶

no_agent¶

no_keys¶

parallel¶

password¶

passwords¶

path¶

pool_size¶

prompts¶

port¶

real_fabfile¶

remote_interrupt¶

rcfile¶

reject_unknown_hosts¶

system_known_hosts¶

roledefs¶

roles¶

shell¶

skip_bad_hosts¶

skip_unknown_tasks¶

ssh_config_path¶

ok_ret_codes¶

sudo_prefix¶

sudo_prompt¶

sudo_user¶

tasks¶

timeout¶

use_shell¶

use_ssh_config¶

user¶

version¶

warn_only¶

環境辞書、 `env`¶

`settings` のコンテキストマネージャー¶

`abort_exception`¶

`abort_on_prompts`¶

`all_hosts`¶

`always_use_pty`¶

`colorize_errors`¶

`combine_stderr`¶

`command`¶

`command_prefixes`¶

`command_timeout`¶

`connection_attempts`¶

`cwd`¶

`dedupe_hosts`¶

`disable_known_hosts`¶

`eagerly_disconnect`¶

`effective_roles`¶

`exclude_hosts`¶

`fabfile`¶

`gateway`¶

`host_string`¶

`forward_agent`¶

`host`¶

`hosts`¶

`keepalive`¶

`key`¶

`key_filename`¶

`linewise`¶

`local_user`¶

`no_agent`¶

`no_keys`¶

`parallel`¶

`password`¶

`passwords`¶

`path`¶

`pool_size`¶

`prompts`¶

`port`¶

`real_fabfile`¶

`remote_interrupt`¶

`rcfile`¶

`reject_unknown_hosts`¶

`system_known_hosts`¶

`roledefs`¶

`roles`¶

`shell`¶

`skip_bad_hosts`¶

`skip_unknown_tasks`¶

`ssh_config_path`¶

`ok_ret_codes`¶

`sudo_prefix`¶

`sudo_prompt`¶

`sudo_user`¶

`tasks`¶

`timeout`¶

`use_shell`¶

`use_ssh_config`¶

`user`¶

`version`¶

`warn_only`¶