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 をセットします。
バージョン 1.4 で追加.
-
-D
,
--disable-known-hosts
¶
env.disable_known_hosts を
True
にセット。Fabric はユーザーの SSHknown_hosts
をロードしません。
-
-f
FABFILE
,
--fabfile
=FABFILE
¶ fabfile を検索するパターン(デフォルトは
fabfile.py
)、あるいは fabfile としてロードする任意のファイルパス(例えば/path/to/my/fabfile.py
)
-
-F
LIST_FORMAT
,
--list-format
=LIST_FORMAT
¶ --list
の出力フォーマットを制御します。.short
は--shortlist
と同じ、normal
は単にこのオプションの省略と同じです(すなわちデフォルト)、そしてnested
はネストされた名前空間のツリーを出力します。バージョン 1.1 で追加.
参考
-
-g
HOST
,
--gateway
=HOST
¶ env.gateway を
HOST
ホスト文字列にセット。バージョン 1.5 で追加.
-
-h
,
--help
¶
すべてのオプションと簡単な説明があるヘルプメッセージを表示して終了します。
-
--hide
=LEVELS
¶ デフォルトで隠すコンマで区切った output levels のリスト。
-
-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)を追加。
-
-p
PASSWORD
,
--password
=PASSWORD
¶ env.password を指定した文字列にセット。SSH接続や
sudo
プログラムで使うデフォルトのパスワードです。
-
-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 はユーザーの SSHknown_hosts
で見つからないホストへの接続を中止します。
-
--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 で追加.
-
--show
=LEVELS
¶ デフォルトで表示されるコンマで区切られた output levels のリスト。
-
--ssh-config-path
¶
env.ssh_config_path をセット。
バージョン 1.4 で追加.
-
--skip-bad-hosts
¶
env.skip_bad_hosts をセット。Fabric は利用できないホストをスキップします。
バージョン 1.4 で追加.
-
--skip-unknown-tasks
¶
env.skip_unknown_tasks をセットすると、見つからないタスクをFabricがスキップします。
-
--timeout
=N
,
-t
N
¶ 接続のタイムアウトを秒で指定します。 env.timeout をセット。
バージョン 1.4 で追加.
-
--command-timeout
=N
,
-T
N
¶ リモートコマンドのタイムアウトを秒で指定します。env.command_timeout
バージョン 1.6 で追加.
-
-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 でデフォルトのユーザー名を気にしなくて済みます。