4.2.2 汎用コマンド実行部品
機能
操作対象の機器で,指定したコマンドを実行できます。
事前に認証情報を[エージェントレス接続先定義]エリアで設定している場合は,汎用コマンド実行部品に次の情報を指定して実行できます。
-
コマンドを実行する操作対象の機器(プロパティ「destinationHost」)
-
実行するコマンド(プロパティ「commandLine」)
-
コマンドの引数(プロパティ「commandLineParameter」)
操作対象の機器で実行するコマンドには,JP1/AOサーバのOSと操作対象の機器のOSの両方のコマンドに入力できる文字を指定してください。例えば,JP1/AOサーバのOSと操作対象の機器のOSが両方とも日本語版のWindowsの場合,MS932の文字セットの範囲の文字が指定できます。
操作対象の機器のOSがWindowsの場合は,プロパティ「runAsSystem」に「true」を指定することで,Systemアカウントの権限でコマンドが実行されます。操作対象の機器のOSがUNIXの場合は,プロパティ「elevatePrivileges」の指定によって,rootユーザーまたは接続ユーザーの権限でコマンドが実行されます。
また,ローカル実行機能が有効の場合,ローカルホストのOSがWindowsのときは,Systemアカウントの権限でコマンドが実行されます。ローカルホストのOSがLinuxのときは,rootユーザーの権限でコマンドが実行されます。
なお,コマンドを実行する際の実行ディレクトリについては,次のとおりです。
-
接続先がWindowsの場合は,Admin$¥Hitachi¥CMALib¥JP1AO¥home
Admin$は,環境変数「windir」と同一のディレクトリを指します。
-
接続先がUNIXの場合でプロパティ「elevatePrivileges」に「true」を指定したときは,rootユーザーのホームディレクトリ
-
接続先がUNIXの場合でプロパティ「elevatePrivileges」に「false」を指定したときは,接続ユーザーのホームディレクトリ
部品のバージョンが02.01.00より前の部品との機能差異については,「付録A.1 基本部品のバージョン間の機能差異」を参照してください。
実行時の前提条件
-
エージェントレス接続先として使用できる操作対象の機器については,「付録A.1(3) エージェントレス接続先として使用できる操作対象の機器」を参照してください。
-
汎用コマンド実行部品を実行する際に,操作対象機器のOSに,あらかじめインストールされている必要のあるコマンドがあります。詳細は,リリースノートを参照してください。
-
操作対象の機器のOSがWindowsで汎用コマンド実行部品を実行する場合,管理共有の設定を有効にする必要があります。詳細については,マニュアル「JP1/AO 導入・設計ガイド」を参照してください。
注意事項
-
コマンド実行時のロケールおよび文字セットは,操作対象の機器のOSによって異なります。詳細については,マニュアル「JP1/AO サービステンプレート開発ガイド」−「部品実行時に設定される操作対象の機器のロケールについて」のトピックおよび「部品実行時にJP1/AO が通信で使用する文字セットについて」のトピックを参照してください。
-
部品の実行中にタスクを実行停止した場合は,汎用コマンド実行部品の処理が完了してからタスクの状態が「失敗」または「正常終了」になります。部品の実行が終了したときのステップおよびタスクの状態は,ステップの戻り値および後続ステップ実行条件によって決まります。後続ステップ実行条件は,[ステップ作成]ダイアログボックスまたは[ステップ編集]ダイアログボックスで設定できます。
-
部品の実行中にタスクを強制停止した場合は,操作対象の機器で実行中のプロセスツリーは直ちに強制終了され,タスクの状態が「失敗」または「正常終了」になります。なお,[タスク]画面の[フロー]エリアに表示されるステップの戻り値は,80になります。タスクログに出力される戻り値は,強制停止したタイミングによって異なります。
-
部品の実行中にタスクを強制停止した場合,プロパティ「commandLine」で指定したコマンドまたはスクリプトの実行結果については製品サポートの対象外となります。
-
操作対象の機器のOSによって,実行方式が異なります。Windowsの場合はSMBおよびRPC,UNIXの場合はSSHを使用します。そのため,UNIXの場合はSSHサーバを操作対象の機器に構築する必要があります。
-
SSHで使用するポート番号は,接続先プロパティファイル(接続先名.properties)またはユーザー設定プロパティファイル(config_user.properties)で設定できます。
-
JP1/AOサーバのOSがLinuxで,かつ操作対象の機器のOSがWindowsの場合は,接続先にIPv6アドレスを指定できません。
-
操作対象の機器のOSがWindowsの場合,ユーザーのプロファイルは引き継がれません。そのため,部品の実行結果と,デスクトップ上で実行したコマンドまたはスクリプトの実行結果は異なることがあります。
よって,部品を実行する際に,ユーザーのプロファイルは参照させないでください。ユーザーのプロファイルとは,ユーザー環境変数,レジストリ,Internet Explorerの設定などです。これらを参照させた場合,コマンドまたはスクリプトが期待する動作をしないことがあります。例えば,Internet Explorerのプロキシの設定を参照するコマンドまたはスクリプトを実行すると,通信エラーで失敗することがあります。これには,Windows Updateをスクリプトで実行する場合などが該当します。
-
操作対象の機器のOSがUNIXで,プロパティ「commandLine」および「commandLineParameter」にASCII文字以外を指定したい場合は,「付録A.4 UNIXでASCII文字以外の文字を含むコマンドラインを実行するための前提条件」を参照してください。
-
ユーザーに入力を求める対話式コマンドおよびスクリプト,GUI表示などにより自動的に終了しないコマンドは実行できません。
バージョン
02.01.00
タグ
Execute Script
戻り値
戻り値 |
説明 |
---|---|
0〜63 |
指定したコマンドまたはスクリプトの戻り値(0〜63)を,そのまま部品の戻り値として返す。そのため,戻り値の意味は,実行したコマンドまたはスクリプトによって異なる。 |
64 |
指定したコマンドまたはスクリプトの戻り値が64以上で終了した場合,部品の戻り値を64で返す。 |
65 |
JP1/AOサーバとの接続に失敗した。例えば,部品実行中にJP1/AOサーバが停止された場合が該当する。 |
66 |
次のユーザーがJP1ユーザーにマッピングされている。
|
68 |
対象のジョブ実行IDに関する情報がない。 |
69 |
タスク処理エンジンの環境変数の取得に失敗した。 |
70 |
操作対象の機器との接続に失敗した。 |
71 |
コマンドの実行に失敗した。 |
72 |
コマンドの実行状態の取得に失敗した。 標準出力および標準エラー出力の合計が100KBを超えた。 |
76 |
接続タイムアウトが発生した。 |
77 |
操作対象の機器のホスト名解決に失敗した。 |
78 |
次のどれかの理由で,操作対象の機器との認証に失敗した。
|
80 |
タスクの実行を停止した。 |
81 |
部品が不正な状態で呼び出された。 |
82 |
タスク処理エンジンからの要求メッセージを正しくパースできない。 |
83 |
JP1/AOサーバの環境が壊れている。 |
84 |
指定された部品の情報が取得できない。 |
86 |
指定したプロパティ値に誤りがある。 |
127 |
そのほかのエラーが発生した。 |
プロパティ一覧
プロパティを次の表に示します。
プロパティキー |
プロパティ名 |
説明 |
デフォルト値 |
入出力種別 |
必須区分 |
---|---|---|---|---|---|
destinationHost |
対象ホスト |
操作対象の機器のIPv4アドレス,IPv6アドレスまたはホスト名を1,024文字以内で指定します。なお,JP1/AOサーバと操作対象の機器は,ネットワークで接続されている必要があります。 なお,複数のIPアドレスまたはホスト名は指定できません。 |
− |
入力 |
○ |
credentialType※1 |
認証種別 |
コマンドまたはスクリプト実行時の認証種別について,次のどちらかを指定します。
|
− |
入力 |
○ |
account※1 |
ユーザーID |
操作対象の機器にログインするためのユーザーIDを256文字以内で指定します。 また,次のどちらかの形式でドメインユーザーを指定できます。
|
− |
入力 |
△ |
password※1 |
パスワード |
操作対象の機器にログインするためのパスワードを256文字以内で指定します。操作対象の機器のOSがUNIXで,プロパティ「publicKeyAuthentication」に「true」を指定した場合は,指定不要です。 |
− |
入力 |
△ |
suPassword※1 |
rootのパスワード |
操作対象の機器のOSがUNIXの場合,rootパスワードを256文字以内で指定します。操作対象の機器のOSがWindowsの場合,またはプロパティ「elevatePrivileges」で「false」を指定した場合は,指定不要です。 |
− |
入力 |
△ |
runAsSystem |
システムアカウントで実行 |
操作対象の機器のOSがWindowsの場合,Systemアカウントの権限でコマンドを実行するかどうかを指定します。操作対象の機器のOSがUNIXの場合,このプロパティに指定した値は無視されます。
|
false |
入力 |
△ |
publicKeyAuthentication※1 |
SSH公開鍵認証設定 |
操作対象の機器のOSがUNIXの場合,接続に公開鍵認証を使用するかどうかについて次のどちらかを指定します。大文字と小文字は区別しません。このプロパティに値を指定しない場合は,「false」として扱われます。操作対象の機器のOSがWindowsの場合は,指定不要です。
|
false |
入力 |
△ |
keyboardInteractiveAuthentication※1 |
SSHキーボードインタラクティブ認証設定 |
操作対象の機器のOSがUNIXの場合,接続にキーボードインタラクティブ認証を使用するかどうかについて次のどちらかを指定します。大文字と小文字は区別しません。このプロパティに値を指定しない場合は,「false」として扱われます。操作対象の機器のOSがWindowsの場合は,指定不要です。 ただし,プロパティ「keyboardInteractiveAuthentication」の値が有効になるのは,「publicKeyAuthentication」に「false」を指定した場合です。「publicKeyAuthentication」に「true」を指定した場合,「keyboardInteractiveAuthentication」に「true」を指定しても,公開鍵認証が設定されます。
|
false |
入力 |
△ |
elevatePrivileges※1 |
権限昇格 |
操作対象の機器のOSがUNIXの場合,rootユーザーに昇格するかどうかについて,次のどちらかを指定します。大文字と小文字は区別しません。このプロパティに値を指定しない場合は,「true」として扱われます。操作対象の機器のOSがWindowsの場合は,指定不要です。
|
false |
入力 |
△ |
commandLine※3 |
コマンドライン |
操作対象の機器で実行したいコマンドまたはスクリプトの絶対パスを256文字以内で指定します。 コマンドラインには,JP1/AOサーバのOSと操作対象の機器のOSの両方のコマンドに入力できる文字を指定してください。 コマンドラインに環境変数を表す特殊文字などが含まれる場合でも,エスケープされません。例えば,エージェントレス接続先がUNIXの環境においてコマンドライン:「echo abc¥def」を実行すると,「abc¥def」とは出力されず,「abcdef」と出力されます。特殊文字を文字列として扱いたい場合,操作対象の機器のOSがWindowsのときは「%」で,操作対象の機器のOSがUNIXのときは「¥」でエスケープした文字を設定してください。 また,コマンドまたはスクリプトは,次のユーザーの権限で実行されます。
|
− |
入力 |
○ |
commandLineParameter※3 |
コマンドラインパラメータ |
コマンドまたはスクリプトの引数を1,024文字以内で指定します。 コマンドラインパラメータには,JP1/AOサーバのOSと操作対象の機器のOSの両方のコマンドに入力できる文字を指定してください。 コマンドラインパラメータに環境変数を表す特殊文字などが含まれる場合でも,エスケープされません。例えば,エージェントレス接続先がWindowsの環境においてコマンドライン:「echo」,コマンドラインパラメータ:「abc%def」を実行すると,「abc%def」とは出力されず,「abcdef」と出力されます。特殊文字を文字列として扱いたい場合,操作対象の機器のOSがWindowsのときは「%」で,操作対象の機器のOSがUNIXのときは「¥」でエスケープした文字を設定してください。 また,コマンドラインパラメータの値として環境変数も指定できます。操作対象の機器のOSによって指定形式が異なります。
|
− |
入力 |
△ |
outputCondition |
標準出力プロパティ出力条件 |
プロパティ「stdoutProperty1〜3」に値を出力する条件を指定します。 指定できる値を次に示します。
|
always |
入力 |
○ |
stdoutProperty1 |
標準出力プロパティ1 |
プロパティ「stdoutPattern1」で切り出した文字列が出力されます。 |
− |
出力 |
△ |
stdoutPattern1 |
標準出力パターン1 |
プロパティ「stdoutProperty1」に出力する標準出力の正規表現パターンを1,024文字以内で指定します。正規表現パターンはPCREに従って指定してください。 プロパティ「stdoutProperty1」にサービスプロパティのキーが指定されている場合,プロパティ「stdoutPattern1」の指定を省略すると,プロパティ「commandLine」で指定したコマンドまたはスクリプトの標準出力および標準エラー出力の内容全体がサービスプロパティに設定されます。 |
− |
入力 |
△ |
stdoutProperty2 |
標準出力プロパティ2 |
プロパティ「stdoutPattern2」で切り出した文字列が出力されます。 |
− |
出力 |
△ |
stdoutPattern2 |
標準出力パターン2 |
プロパティ「stdoutProperty2」に出力する標準出力の正規表現パターンを1,024文字以内で指定します。正規表現パターンはPCREに従って指定してください。 プロパティ「stdoutProperty2」にサービスプロパティのキーが指定されている場合,プロパティ「stdoutPattern2」の指定を省略すると,プロパティ「commandLine」で指定したコマンドまたはスクリプトの標準出力および標準エラー出力の内容全体がサービスプロパティに設定されます。 |
− |
入力 |
△ |
stdoutProperty3 |
標準出力プロパティ3 |
プロパティ「stdoutPattern3」で切り出した文字列が出力されます。 |
− |
出力 |
△ |
stdoutPattern3 |
標準出力パターン3 |
プロパティ「stdoutProperty3」に出力する標準出力の正規表現パターンを1,024文字以内で指定します。正規表現パターンはPCREに従って指定してください。 プロパティ「stdoutProperty3」にサービスプロパティのキーが指定されている場合,プロパティ「stdoutPattern3」の指定を省略すると,プロパティ「commandLine」で指定したコマンドまたはスクリプトの標準出力および標準エラー出力の内容全体がサービスプロパティに設定されます。 |
− |
入力 |
△ |
- 注※1
-
ローカル実行機能が有効で,操作対象がローカルホストの場合,設定内容は無視されます。
- 注※2
-
プロパティ「publicKeyAuthentication」および「keyboardInteractiveAuthentication」の両方に「false」を指定した場合,パスワード認証が設定されます。
- 注※3
-
-
これらのプロパティに指定されたコマンドまたはスクリプトの,標準出力および標準エラー出力は,JP1/AOのステップの標準出力として出力されます。ただし,コマンドまたはスクリプトの,標準出力および標準エラー出力の合計が100KBを超えた場合の処理の実行結果については,製品サポートの対象外となります。事前に,コマンドまたはスクリプトを実行して,標準出力および標準エラー出力の合計が100KBを超えていないことを確認してください。
-
操作対象の機器のOSがWindowsの場合,プロパティ「commandLine」および「commandLineParameter」で指定した内容は,バッチファイル化され操作対象の機器で実行されます。そのため,対象のコマンドまたはスクリプトをコマンドプロンプトで実行した結果と異なることがあります。
-
操作対象の機器のOSがUNIXの場合,標準出力および標準エラー出力の改行コードは,次のとおり変更されます。
-
「CR(0x0d)」が「LF(0x0a)」に変更される。
-
「CR+LF(0x0d0a)」が「LF+LF(0x0a0a)」に変更される。
また,標準出力および標準エラー出力の最後の文字列が改行コード(「CR」,「LF」または「CR+LF」)以外の場合は,末尾に「LF(0x0a)」が付加されます。
-
-
プロパティ「stdoutPattern1〜3」および「stdoutProperty1〜3」の使用例
標準出力および標準エラー出力をプロパティ「stdoutPattern1〜3」の値と照合した結果を,プロパティ「stdoutProperty1〜3」にそれぞれ格納できるようになります。次の図に,「stdoutPattern1」に「aaabbb(.*)」を指定した場合のデータの流れを示します。
|
標準出力「aaabbbccc」に対して,「stdoutPattern1」で定義しているように,標準出力の「aaabbb」より後ろの値(ccc)が抽出されます。抽出された値は,プロパティ「stdoutProperty1」に格納されます。
プロパティ「stdoutPattern1〜3」で指定した正規表現が標準出力と合致せず値を抽出できなかった場合に,プロパティ「stdoutProperty1〜3」に値を格納するかどうかは,プロパティ「outputCondition」で指定できます。
SSHで使用するポート番号の指定
操作対象の機器にSSHを使用して接続する場合は,ポート番号を指定できます。ポート番号を指定する方法と優先順位は,次のとおりです。
優先順位 |
設定個所 |
プロパティキー |
デフォルト値 |
---|---|---|---|
1 |
接続先プロパティファイル(接続先名.properties) |
ssh.port |
− |
2 |
ユーザー設定プロパティファイル(config_user.properties) |
ssh.port.number |
22 |
- (凡例)
-
−:値は設定されていません。
関連トピック
-
マニュアル「JP1/AO 導入・設計ガイド」−「エージェントレス接続先の前提条件」のトピック
-
マニュアル「JP1/AO 構築ガイド」−「ユーザー設定プロパティファイル(config_user.properties)」および「接続先プロパティファイル(接続先名.properties)」のトピック