fab オプションと引数

Fabric の最も普通の使い方はコマンドライン・ツールとしてです。fab はFabricがインストールされた時にシェルの実行パスに置かれているはずです。 fab はUnixの良い住民になろうと努力しています。標準のコマンドライン・スイッチやヘルプ出力など。

基本的な使い方

最もシンプルなものでは fab は全くオプションなしで、あるいは1つか2つのタスク名を引数として呼ばれます。例えば:

$ fab task1 task2

概要とチュートリアル と 実行モデル で詳しく説明されていますが、これは task1 に続き task2 を実行します。ただし Fabricがこれらの名前のPython関数を含んだfabfileを見つけられればですが。

しかしオプションやそれぞれのタスクに渡される引数を使ってさらにフレキシブルに拡張することができます。

任意のリモートシェル・コマンド

バージョン 0.9.2 で追加.

Fabric はあまり知られていないコマンドラインの記述で次のように呼ぶこともできます:

$ fab [options] -- [shell command]

-- の後はすべて一時的な run コールとなり fab オプションとは解釈しません。モジュールレベルやコマンドラインでホストリストを定義すれば、これは一行の anonymous タスクのように使えます。

例えばシステムのカーネル情報をまとめて取得するにはこの様にします:

$ fab -H system1,system2,system3 -- uname -a

これは以下の fabfile と同じです:

from fabric.api import run

def anonymous():
    run("uname -a")

まるでこれが実行されたように:

$ fab -H system1,system2,system3 anonymous

ほとんどの場合タスクは fabfile に書くことになるでしょう。(一度使ったものは、もう一度使うことになるでしょうから) しかしこの機能は fabfile の接続設定を利用している時に手軽ですばやく SSH-borne コマンドを実行できます。

コマンドライン・オプション

利用可能なコマンドライン・オプションの概要は fab --help で表示できます。オプションの詳細は以下です。

注釈

fab は Python の optparse ライブラリを使います。これは Linux や GNU スタイルのショートやロングオプションが使えるということです。また自由にオプションと引数を使えます。例えば fab task1 -H hostname task2 -i path/to/keyfile はもっとわかりやすく fab -H hostname -i path/to/keyfile task1 task2 と書けます。

-a, --no_agent

env.no_agent を True にセット。SSH レイヤーにプライベートキーをアンロックするときに SSH エージェントと接続しないように強制します。

バージョン 0.9.1 で追加.

-A, --forward-agent

env.forward_agent を True にセット。エージェントのフォワードを有効にします。

バージョン 1.4 で追加.

--abort-on-prompts

env.abort_on_prompts を True にセット。入力を要求されたら Fabric を中断するよう強制します。

バージョン 1.1 で追加.

-c RCFILE, --config=RCFILE

env.rcfile を指定のファイルにセット。Fabric はこれを起動時に読み込み環境変数を更新します。

-d COMMAND, --display=COMMAND

指定したタスクのドキュメント文字列をすべて表示します。タスクの関数のシグネチャーは表示しません。 ドキュメント文字列を説明に使うのは良いアイデアです。(They're always a good idea, of course -- just moreso here.)

--connection-attempts=M, -n M

接続を試みる回数を指定。env.connection_attempts をセットします。

参考

env.connection_attempts, env.timeout

バージョン 1.4 で追加.

-D, --disable-known-hosts

env.disable_known_hosts を True にセット。Fabric はユーザーの SSH known_hosts をロードしません。

-f FABFILE, --fabfile=FABFILE

fabfile を検索するパターン(デフォルトは fabfile.py)、あるいは fabfile としてロードする任意のファイルパス(例えば /path/to/my/fabfile.py)

参考

fabfileの構成と使い方

-F LIST_FORMAT, --list-format=LIST_FORMAT

--list の出力フォーマットを制御します。. short は --shortlist と同じ、 normal は単にこのオプションの省略と同じです(すなわちデフォルト)、そして nested はネストされた名前空間のツリーを出力します。

バージョン 1.1 で追加.

参考

--shortlist, --list

-g HOST, --gateway=HOST

env.gateway を HOST ホスト文字列にセット。

バージョン 1.5 で追加.

-h, --help

すべてのオプションと簡単な説明があるヘルプメッセージを表示して終了します。

--hide=LEVELS

デフォルトで隠すコンマで区切った output levels のリスト。

-H HOSTS, --hosts=HOSTS

env.hosts をコンマで区切ったホスト文字列のリストにセット。

-x HOSTS, --exclude-hosts=HOSTS

最終ホストリストの他に env.exclude_hosts に与えられたコンまで区切ったホスト文字列のリストをセットします。

バージョン 1.1 で追加.

-i KEY_FILENAME

ファイルのパスをセットすると SSH認証ファイルとしてロードします。(通常はプライベート鍵) このオプションは何度も繰り返されるかもしれません。env.key_filename にセット(あるいは追加)します。

-I, --initial-password-prompt

pre-fill env.password のためにセッション開始時にパスワードを要求するように強制します。(fabfile をロードしてオプションを解析してタスクを実行する直前)。

これはパスワードを --password や fabfileの env.password で設定したくない時に(特に実行時に入力が不可能な並行セッションで)走らせて放置(fire-and-forget)できるので便利です。

注釈

ここでの入力はモジュールレベルの env.password や --password を 上書き します。

参考

パスワード管理

-k

env.no_keys を True にセット。SSH レイヤーはホームのプライベート・キーファイルを探しません。

バージョン 0.9.1 で追加.

--keepalive=KEEPALIVE

env.keepalive を指定した整数にセット。SSH キープアライブの間隔を指定します。

バージョン 1.1 で追加.

--linewise

強制的に出力バッファをバイトごとでなく行ごとにします。parallel execution に有効でありまた必要になります。

バージョン 1.3 で追加.

-l, --list

通常通り fabfile をインポートして見つかったタスクのリストを表示して終了します。またタスクのドキュメント文字列の最初の行を表示します。必要なら切り詰めます。

バージョン 0.9.1 で変更: 出力にドキュメンテーション文字列(docstring)を追加。

参考

--shortlist, --list-format

-p PASSWORD, --password=PASSWORD

env.password を指定した文字列にセット。SSH接続や sudo プログラムで使うデフォルトのパスワードです。

参考

--initial-password-prompt

-P, --parallel

env.parallel を True にセット。タスクを並行処理します。

バージョン 1.3 で追加.

参考

並列実行

--no-pty

env.always_use_pty を False にセット。すべての run/sudo の呼び出しは pty=False の指定と同じになります。

バージョン 1.0 で追加.

-r, --reject-unknown-hosts

env.reject_unknown_hosts を True にセット。Fabric はユーザーの SSH known_hosts で見つからないホストへの接続を中止します。

-R ROLES, --roles=ROLES

env.roles をコンマで区切られた role名のリストにセット。

--set KEY=VALUE,...

デフォルトのy Fabric の env の値を任意の値にセット。しかしこの方法の優先度は低くなります。 -- コマンドラインで指定された env の値を上書きできません。例えば:

fab --set password=foo --password=bar

これは env.password = 'bar' となります。

複数の KEY=VALUE はカンマで区切ります。例えば fab --set var1=val1,var2=val2 のように。

基本的な文字列の他に =VALUE を省略することで env は True になります。(例えば fab --set KEY), and you may set values to また イコールは使って``VALUE`` を省略することで空の文字列(そして False と等価)にセットできます。(例えば fab --set KEY=)

バージョン 1.4 で追加.

-s SHELL, --shell=SHELL

env.shell を指定した文字列にセット。リモートコマンドの実行に使用するデフォルト・シェルを変更します。

--shortlist

--list に似ているがどんな修飾もなくインデンテーションやドキュメント文字列もない改行で区切られたタスク名。

バージョン 0.9.2 で追加.

参考

--list

--show=LEVELS

デフォルトで表示されるコンマで区切られた output levels のリスト。

参考

run, sudo

--ssh-config-path

env.ssh_config_path をセット。

バージョン 1.4 で追加.

参考

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

--skip-bad-hosts

env.skip_bad_hosts をセット。Fabric は利用できないホストをスキップします。

バージョン 1.4 で追加.

--skip-unknown-tasks

env.skip_unknown_tasks をセットすると、見つからないタスクをFabricがスキップします。

参考

env.skip_unknown_tasks

--timeout=N, -t N

接続のタイムアウトを秒で指定します。 env.timeout をセット。

参考

env.timeout, env.connection_attempts

バージョン 1.4 で追加.

--command-timeout=N, -T N

リモートコマンドのタイムアウトを秒で指定します。env.command_timeout

参考

env.command_timeout,

バージョン 1.6 で追加.

-u USER, --user=USER

env.user を指定の文字列にセット。SSH 接続を行なうときにデフォルトのユーザー名として使われます。

-V, --version

Fabric のバージョンを表示して終了します。

-w, --warn-only

env.warn_only を True にセット。Fabric はコマンドがエラーを起こしても実行を続けます。

-z, --pool-size

env.pool_size をセット。並行処理で同時に実行するプロセスの数を指定します。

バージョン 1.3 で追加.

参考

並列実行

Per-task 引数

コマンドライン・オプション で与えられたオプションは fab 呼び出しの全体に適用されます。順番によらずオプションは等しくタスクに与えられます。加えてタスクは Python関数なので引数は実行時に渡されるのが望ましいでしょう。

この両方のニーズに答えるのが "per-task 引数" のコンセプトです。これはタスク名に添える特殊な構文です:

• 引数とタスク名を区別するにはコロン (:) を使います;
• コンマ (,) を引数を区別するために使います。(バックスラッシュでエスケープします。例えば \,);
• イコール (=) はキーワード引数、あるいは位置パラメーターの省略に使います。バックスラッシュでエスケープします。

このプロセスは文字列解析を呼び出します。すべての値は Python 文字列になります。(直感的な構文が見つかれば将来のバージョンの Fabric で改良します。)

例えば、 "create a new user" タスクはこの様に定義できます。(簡単にするために実際のロジックは省略):

def new_user(username, admin='no', comment="No comment provided"):
    print("New User (%s): %s" % (username, comment))
    pass

ユーザー名だけを指定できます:

$ fab new_user:myusername

あるいは任意のキーワード引数として扱います。

$ fab new_user:username=myusername

もし両方が与えられたら、再び位置パラメーターとして:

$ fab new_user:myusername,yes

あるいは Python のように mix and matchで:

$ fab new_user:myusername,admin=yes

上記の print の呼び出しはコンマのエスケープの説明に有効です。このように:

$ fab new_user:myusername,admin=no,comment='Gary\, new developer (starts Monday)'

注釈

コンマはバックスラッシュでエスケープします。そうしないとシンタックスエラーになります。クォートもまた引数にスペースのようなシェルの特殊文字を含むときには必要になります。

上記のすべては期待される Python関数の呼び出しに変換されます。例えば最後の呼び出しはこのように::(訳注:adminの値がおかしい)

>>> new_user('myusername', admin='yes', comment='Gary, new developer (starts Monday)')

Roles と hosts

the section on task execution で言及したようにいくつかの per-task キーワード引数があります。(host, hosts, role ,``roles``) これは実際にはタスク関数にマッピされませんが per-task host や roleリストの設定に使われます。

これらの特殊な kwargs は args/kwargs から 取り除かれて タスク関数に送られます。これはタスクが問題の kwargs を定義していないなら TypeErrors になりません。doesn't define the kwargs in question. (これはまたこれらの名前の引数を定義して いた らこの方法で指定することはできません -- 残念なことに必要な犠牲。)

注釈

kwargs に plural と singular の両方が与えられたら、plural の値が優先され singular は棄てられます。

これらの引数に plural を使うときセミコロン(;)を使います。コンマは引数で使います。さらにシェルがセミコロンを特殊文字として扱わないようにホストリストにはクォートを使うほうがよいでしょう。例えば:

$ fab new_user:myusername,hosts="host1;host2"

new_user タスク関数に送られるとき hosts kwarg は引数リストから除かれます。実際、Python の呼び出しは new_user('myusername') で, ['host1', 'host2'] のホストリストで関数が実行されます。

設定ファイル

Fabric は現在シンプルなユーザー設定ファイル、fabricrc (fab のための bashrc のような)を使います。これには一つ以上の キー/値 のペアの行があります。書式は string.split('=') に従います。現在は特定の文字列の設定に使われます。このようなキー/値のペアは fab が実行されるときに env の更新に使われます。これは fabfile が読み込まれる前にロードされます。

デフォルトで Fabric は ~/.fabricrc 探しますが、これは fab のオプション -c で変更できます。

例えばワークステーションのユーザー名と SSH ログインのユーザー名が違うときにプロジェクトで使う fabfile の env.user を変更したくはないでしょう。(恐らく他の人も使うでしょうから) fabricrc ファイルをこの様にします:

user = ssh_user_name

これで fab を実行するときに fabfile の env.user は 'ssh_user_name' になります。他のユーザーの fabfile も同様にすると fabfile でデフォルトのユーザー名を気にしなくて済みます。