dagtools

IIJ IoTサービス ストレージ専用コマンドラインツール

 

インストール

ご利用の環境に該当するパッケージを以下からダウンロードしてご利用ください。

 

設定

INI形式の設定ファイルを /etc/dagtools.ini もしくはカレントディレクトリに配置するか -f オプションでコマンド実行時に指定します。
設定パラメータは以下の通りです。


[dagtools] セクション
proxyHTTP Proxy を指定
verboseコマンドの実行内容を表示(-v オプションと同じ)
debugデバッグモードで実行(-d オプションと同じ)
concurrency
並列実行数(default: 1)
マルチパートアップロードの際のパートのアップロードの並列実行数となります。
tempDir
一時ファイルの保存先
標準入力を使用したアップロードの場合は一時的にこのディレクトリの保存されます。
[logging] セクション
typeログ出力の種類(none, file, stdout, stderr)
filefile タイプ時の出力先のファイルパス
[storage] セクション
endpointIIJ IoTサービスのStorage APIのエンドポイント
accessKeyIdAPIのアクセスキーID
secretAccessKeyAPIのシークレットアクセスキー
secureSSL/TLSプロトコルを用いた通信の暗号化(HTTPS)を使用するかどうか(true,false)
multipartChunkSize
マルチパートアップロードのチャンクサイズ(Bytes)。
アップロードするファイルが指定のサイズより大きい場合にはマルチパートアップロードとなり、 このサイズで分割してアップロードします。このサイズを下回る場合にはPUT Objectとなります。
retry
HTTP/HTTPS リクエスト失敗時のリトライ回数 (デフォルト: 2)
リトライしない場合は 0 を指定してください。
retryInterval
リトライを実施する間隔(ミリ秒単位, デフォルト: 3000)
1秒 = 1000 となります。

 

設定例

[dagtools]
debug = false
verbose = true
proxy =
concurrency = 2
tempDir = /var/tmp

[logging]
type = file
file = dagtools.log

[storage]
endpoint = s3api.iot.iij.jp
accessKeyId = <Access Key Id>
secretAccessKey = <Secret Access Key>
secure = true
multipartChunkSize = 1073741824 # 1GB
retry = 2 # number of retries
retryInterval = 3000 # 3.0 seconds

<Access Key Id> および <Secret Access Key> はサービスオンラインより払い出されたアクセスキーIDとシークレットアクセスキーとなります。

認証情報が含まれるファイルですので、ファイルの権限設定など適切に行ってください。

 

使い方

Usage:
  dagtools [-h] [-d] [-v] [-f <config file>] <command> [<args>]

Options:
  -d    debug mode
  -f string
        specify an alternate configuration file (default: ./dagtools.ini or /etc/dagtools.ini)
  -h    print a help message and exit
  -v    verbose mode
  -version
        show version

Commands:
          ls: list buckets or objects
         cat: get an object and print to standard output
         get: get an object and write to a file
       exist: check to exist buckets/objects
          rm: delete a bucket or object[s]
         put: put a bucket or object[s]
        help: print a command usage
        sync: synchronize with objects on DAG storage and local files
      policy: manage a bucket policy (put, cat, rm)
       space: display used storage space
     traffic: display network traffics

 

実行例

バケット新規作成(PUT Bucket)
$ dagtools put mybucket

 

ファイルのアップロード(PUT Object)

単一のファイルをアップロード:

 $ dagtools put path/to/file mybucket:foo/bar/my-object
or
$ dagtools put mybucket:foo/bar/my-object < path/to/file

複数のファイルをアップロード:

$ dagtools put path/to/file1 path/to/file2 mybucket:foo/bar/
$ dagtools put path/to/file* mybucket:foo/bar/

ディレクトリを指定してアップロード:

# 以下の場合はオブジェクトキーにディレクトリ名を含みます (foo/bar/dir/...)
$ dagtools put -r path/to/dir/ mybucket:foo/bar/

# 以下の場合はオブジェクトキーにディレクトリ名は含みません (foo/bar/...)
$ dagtools put -r path/to/dir/ mybucket:foo/bar

 

オブジェクトの取得(GET Object)

カレントディレクトリに書き出す:

$ dagtools get mybucket:foo/bar/my-object

上記の例では my-object というファイル名でカレントディレクトリに保存されます。

 

書き込み先を指定して書き出す:

 $ dagtools get mybucket:foo/bar/my-object path/to/file

ディレクトリを指定して一括で取得する:

$ dagtools get -r mybucket:foo/bar/dir/ path/to/directory/ 
  • 末尾にスラッシュを付けた場合には、そのディレクトリにサブディレクトリを作成します。(上記の例では path/to/directory/dar/ が作られます)
  • 逆に付けなかった場合には、そのディレクトリ名に置き換えられます。(上記の例では foo/bar/dir/path/to/directory/ として格納します)

オブジェクトの内容を表示(標準出力):

 $ dagtools cat mybucket:foo/bar/my-object
バケットの削除(DELETE Bucket)

空のバケットを削除:

 $ dagtools rm mybucket

オブジェクトが1つ以上存在する場合は削除されません。

バケット内の全てオブジェクトも一緒に削除:

 $ dagtools rm -r mybucket
オブジェクトの削除(DELETE Objects)

単一のオブジェクトを削除:

$ dagtools rm mybucket:foo/bar/my-object

ディレクトリを指定して削除:

$ dagtools rm -r mybucket:foo/bar/

ファイルのプレフィックスを指定して削除:

$ dagtools rm mybucket:foo/bar/my-*

削除したオブジェクトを表示:

$ dagtools rm -v -r mybucket:foo/

 

バケットの一覧表示(List Buckets)
 $ dagtools ls

 

オブジェクトの一覧表示(List Objects)

ルートディレクトリのオブジェクト一覧:

 $ dagtools ls mybucket

指定したディレクトリのオブジェクト一覧:

$ dagtools ls mybucket:foo
or
$ dagtools ls mybucket:foo/

オブジェクトのサイズを読みやすい形式(Human-Readable)で表示:

$ dagtools ls -h mybucket:foo

サブディレクトリを再帰的に表示:

$ dagtools ls -r mybucket:foo

指定したファイルのプレフィックスに一致するオブジェクトのみ表示:

$ dagtools ls mybucket:foo/bar/my*

TSV形式で表示:

$ dagtools ls -tsv mybucket:foo

ETagも含めてリストを表示する:

$ dagtools ls -etag mybucket:foo
ディレクトリを同期
  • ローカルのディレクトリとDAGストレージのバケット/ディレクトリ間で片方向の同期を行う機能です。
  • ファイルの更新日時とサイズを元に変更を検出し、2回目以降の同期は変更されているファイルのみアップロード/ダウンロードします。
  • ファイルの削除は同期されません

リモートストレージからローカルのディレクトリに同期:

$ dagtools sync mybucket:foo/bar/ /path/to/local-dir/

ローカルのディレクトリからリモートストレージに同期:

$ dagtools sync /path/to/local-dir/ mybucket:foo/bar/

同期の状況を表示:

 $ dagtools -v sync /path/to/local-dir/ mybucket:foo/bar/

確認(dry-run):

 $ dagtools -v sync -n /path/to/local-dir/ mybucket:foo/bar/
バケットポリシーの登録(PUT Bucket policy)
$ dagtools policy put mybucket policy.json
or
$ dagtools policy put mybucket < policy.json
バケットポシリーの取得(GET Bucket policy)

標準出力に表示:

$ dagtools policy cat mybucket
バケットポリシーの削除(DELETE Bucket policy)
$ dagtools policy rm mybucket
ストレージ使用量の取得(GET Service space)
$ dagtools space
ストレージに対するネットワーク通信量の取得(GET Service traffic)

日付を指定して取得:

$ dagtools traffic 20150401

先月1日から今日までの一覧を取得する:

$ dagtools traffic -b 1
バケットまたはオブジェクトの存在確認(HEAD Bucket, HEAD Object)

バケットの存在確認:

$ dagtools exist mybucket

オブジェクトの存在確認:

$ dagtools exist mybucket:foo
  • 終了ステータスで結果を確認することができます。存在する場合: 0存在しない場合(エラー): 1

  • 表示オプション(-v)が有効の場合は標準出力に結果を表示します。

  • コマンド引数に複数のバケットまたはオブジェクトを指定することもできます。

 

その他

終了ステータスについて

終了ステータスはdagtools返されたサービスからのレスポンス内容を反映します。

  • 終了ステータス

    • レスポンスが2xxだった場合: 0

    • レスポンスが4xx又は5xxだった場合: 1

終了ステータスは、一般的な方法でスクリプトから参照する事が可能です。 たとえばWindowsであれば環境変数 %ERRORLEVEL% を参照する事で、またLinuxであれば $? を参照する事で値を確認できます。

エラー時のメッセージについて

dagtoolsが何らかのエラーを受け取った場合、以下のフォーマットで標準エラー出力にメッセージが出力されます。

[Error] <レスポンスコード> <メッセージ> (<リクエストID>)
  • レスポンスコードは、受信したHTTPレスポンスコードです。
  • メッセージは、発生した問題を記述したメッセージです。
  • リクエストIDは個々のリクエストに付与される識別子で、サポートへのお問い合わせの際にお知らせ頂くものです。