gcsfuse CLI

このページでは、Cloud Storage FUSE の操作に使用する gcsfuse コマンドライン オプションについて説明します。

概要

gcsfuse GLOBAL_OPTIONS BUCKET_NAME MOUNT_POINT

ここで

  • GLOBAL_OPTIONS は、マウントの設定方法と Cloud Storage FUSE の動作を制御するオプションです。

  • BUCKET_NAME は、マウントするバケットの名前です。例: my-mount-bucket。省略可。動的マウントを実行するときに、このコマンドからバケット名を除外します。

  • MOUNT_POINT は、バケットがマウントされるローカル ディレクトリです。例: /path/to/mount/point。

説明

gcsfuse CLI は、Cloud Storage バケットをファイル システムとしてローカルマシンにマウントするために使用します。

グローバル オプション

グローバル オプション 説明
--anonymous-access BOOLEAN リクエストの認証を無効にします。このフラグは、認証をサポートしていないカスタム エンドポイントを使用している場合に設定する必要があります。一般公開バケットで Cloud Storage FUSE を使用している場合も、このフラグを設定する必要があります。デフォルト値は false です。
--app-name VALUE マウントのアプリケーション名。
--billing-project VALUE マウントされたバケットにアクセスされたときに、課金に使用するプロジェクトを指定します。リクエスト元による支払いで有効にしたバケットをマウントするときに、多くの場合、このフラグは必要になります。デフォルトのプロジェクトはありません。
--cache-dir VALUE ファイル キャッシュ データを格納するディレクトリを指定します。

注: ファイル キャッシュを有効にするには、--cache-dir を使用してディレクトリを指定し、--file-cache-max-size-mb フラグを使用して、特定の最大ファイル キャッシュ サイズの上限を Mebibyte（MiB）単位の正の整数で指定するか、-1 の値を使用して上限を指定する必要があります。
--client-protocol VALUE Cloud Storage バックエンドとの通信に使用されるプロトコルを指定します。HTTP/1.1 の場合、値は http1 になり、HTTP/2 の場合は http2 になります。デフォルト値は http1 です。
--config-file VALUE Cloud Storage FUSE の動作の構成に使用する構成ファイルのパスを指定します。例: --config-file /etc/gcsfuse.yaml
--custom-endpoint VALUE データを取得するための代替カスタム エンドポイントを指定します。カスタム エンドポイントは、Cloud Storage JSON エンドポイント https://storage.googleapis.com/storage/v1 と同等のリソースとオペレーションをサポートする必要があります。 カスタム エンドポイントが指定されていない場合、Cloud Storage FUSE はグローバル Cloud Storage JSON API エンドポイント https://storage.googleapis.com/storage/v1 を使用します。 指定したカスタム エンドポイントで認証がサポートされていない場合は、--anonymous-access フラグを true に設定して認証をバイパスします。
--debug_fuse BOOLEAN 非推奨。FUSE 関連のデバッグ出力を有効にします。このオプションは --log-severity オプションに置き換えられました。デバッグ出力を有効にするには、--log-severity オプションを trace に設定します。これには、トレースログ、デバッグログ、情報ログ、警告ログ、エラーログが含まれます。
--debug_gcs BOOLEAN 非推奨。Cloud Storage のリクエストとタイミング情報を出力します。このオプションは --log-severity オプションに置き換えられました。デバッグ出力を有効にするには、--log-severity オプションを trace に設定します。これには、トレースログ、デバッグログ、情報ログ、警告ログ、エラーログが含まれます。
--debug_invariants BOOLEAN 内部不変条件違反が検出されると、プログラムを終了します。デフォルト値は false です。
--debug_mutex BOOLEAN ミューテックスの保持時間が長くなりすぎると、デバッグ メッセージを出力します。このオプションを指定すると、ログの重大度が自動的に trace に設定されます。これには、トレースログ、デバッグログ、情報ログ、警告ログ、エラーログが含まれます。デフォルト値は false です。
--dir-mode VALUE ディレクトリの権限ビット（8 進数）。最小値は 000、最大値は 777 です。デフォルト値は 755 です。
--enable-nonexistent-type-cache BOOLEAN Cloud Storage でファイルが見つからない場合、NonexistentType 型のキャッシュ エントリが作成されます。ファイルが Cloud Storage で作成されても、ファイルの NonexistentType エントリがキャッシュに保存されている場合、Cloud Storage FUSE は、NonexistentType エントリがタイプ キャッシュから削除されるまで、そのファイルをリクエストできません。デフォルト値は false です。
--file-cache-cache-file-for-range-read BOOLEAN

ゼロ以外のオフセットから最初の読み取りが行われたときに、オブジェクト全体を非同期的にダウンロードして Cloud Storage FUSE キャッシュ ディレクトリに保存するかどうかを示します。複数のランダム読み取りまたは部分読み取りを行う場合は、このフラグを true に設定する必要があります。このフィールドを省略した場合、デフォルト値の false が使用されます。

注: オフセット 0 から部分読み取りを行う場合、Cloud Storage FUSE は完全なオブジェクトを非同期でダウンロードしてキャッシュに保存します。
--file-cache-download-chunk-size-mb VALUE

オブジェクトをファイル キャッシュにダウンロードするときに、各 goroutine が Cloud Storage に対して行う 1 回の読み取りリクエストのサイズを MiB で指定します。デフォルト値は 50 です。
--file-cache-enable-parallel-downloads BOOLEAN

ファイル キャッシュ ディレクトリをプリフェッチ バッファとして使用し、複数のワーカーを使用してサイズの大きいファイルを並列でダウンロードすることで、サイズの大きいファイルの読み取りを高速化します。デフォルト値は false です。


並列ダウンロードを使用するには、ファイル キャッシュを有効にする必要があります。並列ダウンロードと、そのサポート プロパティの構成方法について詳しくは、並列ダウンロードを使用して読み取りパフォーマンスを改善するをご覧ください。
--file-cache-max-parallel-downloads VALUE

ファイルのダウンロード ジョブ全体で、任意の時点で生成できる goroutine の最大数。デフォルトは、マシン上の CPU コア数の 2 倍、または 16 のいずれか大きいほうです。上限を指定しない場合は、値 -1 を入力します。
--file-mode VALUE ファイルの権限ビットを 8 進数で指定します。最小値は 000、最大値は 777 です。デフォルト値は 644 です。
--foreground BOOLEAN フォアグラウンドで gcsfuse コマンドを実行します。 デフォルト値は false です。
--gid VALUE すべての i ノードのグループ識別子（GID）オーナーを指定します。値には整数を指定してください。デフォルト値は -1 です。
--help または -h Cloud Storage FUSE に関するヘルプを表示します。
version または -v インストールした Cloud Storage FUSE のバージョンが表示されます。
--http-client-timeout VALUE Cloud Storage FUSE HTTP クライアントがタイムアウトになる前にサーバーからのレスポンスを待つ時間を指定します。値は時間の長さである必要があります。例: 1h10m10sデフォルト値は 0s で、タイムアウトがないことを示します。
--ignore-interrupts VALUE Control+C によってトリガーされる SIGINT など、システム割り込みシグナルを無視するように Cloud Storage FUSE に指示します。これにより、実行中のオペレーションがシグナルによって終了することがなくなります。値は true または false です。デフォルト値は true です。
--implicit-dirs BOOLEAN

フォルダとマネージド フォルダが暗黙的に含まれています。

詳細については、GitHub のファイルとディレクトリのドキュメントをご覧ください。 デフォルト値は false です。
--kernel-list-cache-ttl-secs VALUE リスト キャッシュを有効にし、キャッシュに保存されたリストエントリの有効期間（TTL）を秒単位で定義します。リスト キャッシュはページ キャッシュのメモリに保持され、使用可能なメモリに基づいてカーネルによって制御されます。デフォルト値は 0 で、リストのキャッシュが無効になります。

--kernel-list-cache-ttl-secs フラグを設定するには、ディレクトリ リスト レスポンスをカーネルのページ キャッシュに保持する時間を秒単位の正の整数で指定します。エントリの有効期限をバイパスし、キャッシュから利用可能な場合に常にキャッシュからリスト レスポンスを返すには、-1 の値を指定します。
--key-file VALUE Cloud Storage へのリクエストを認証するための認証情報 JSON キーファイルの絶対パスを指定します。デフォルトでは、Cloud Storage FUSE はアプリケーションのデフォルト認証情報を使用してリクエストを認証します。
--limit-bytes-per-sec VALUE Cloud Storage FUSE が Cloud Storage からデータを読み込むことができる帯域幅の上限を指定します。測定時間は 30 秒です。値は浮動小数点数で指定する必要があります。デフォルトの上限値は -1 で、この場合、上限はありません。
--limit-ops-per-sec VALUE 30 秒間に測定される 1 秒あたりのオペレーションの上限を指定します。値は浮動小数点数で指定する必要があります。デフォルトの上限値は -1 で、この場合、上限はありません。
--log-file VALUE Fluentd で解析できるログを保存するためのファイルを指定します。指定しないと、Cloud Storage FUSE がフォアグラウンドで実行されている場合は stdout に書式なしテキストのログが出力されます。Cloud Storage FUSE がバックグラウンドで実行されている場合は syslog に出力されます。
--log-format VALUE ログファイルの形式を指定します。値は text または json にする必要があります。デフォルト値は json です。
--log-rotate-backup-file-count VALUE ローテーション後に保持しておくログファイルの最大数。ログが書き込まれているアクティブなファイルは除きます。値を 0 に設定すると、ローテーションされたログファイルがすべて保持されます。このフィールドを省略した場合、デフォルト値の 10 が使用されます。
--log-rotate-compress BOOLEAN ローテーションされたログファイルを gzip で圧縮するかどうかを指定するブール値。このフラグを省略した場合、デフォルト値の true が使用されます。
--log-rotate-max-file-size-mb VALUE ログファイルがローテーションされる前に到達可能な最大サイズ（MB 単位）。最小値は 1 です。このフィールドを省略した場合、デフォルト値の 512 が使用されます。
--log-severity ENUM

Cloud Storage FUSE で生成するログの重大度。列挙型で表します。値が小さいほど重大度が低く、大きいほど高くなります。

  • trace
  • debug
  • info
  • warning
  • error

重大度レベルを指定すると、Cloud Storage FUSE は、重大度が同等以上のログを生成します。たとえば、warning を指定すると、Cloud Storage FUSE は警告とエラーのログを生成します。通常は、info の重大度レベルを使用することをおすすめします。off を指定して、すべてのロギングをオフにすることもできます。コマンドの一部として --debug_mutex を指定すると、重大度レベルは自動的に trace に設定され、log-severity がオーバーライドされます。

このフィールドを省略した場合、デフォルト値の info が使用されます。

注: ファイル キャッシュが有効になっているときに trace または debug の重大度レベルを使用すると、ロギングのオーバーヘッドによりパフォーマンスが低下する可能性があるため、トラブルシューティング時など一時的にのみ使用してください。
--max-conns-per-host VALUE サーバーごとに許可される TCP 接続の最大数を指定します。これは、--client-protocol が http1 に設定されている場合に有効になります。値は 0～2147483647 の範囲で指定してください。デフォルト値は 0 です。これは、マシンの仕様で設定された上限を除き、TCP 接続に上限が存在しないことを指定します。
--max-idle-conns-per-host VALUE サーバーごとに許可されるアイドル接続の最大数を指定します。値は 0～2147483647 の範囲で指定してください。デフォルト値は 100 です。
--max-retry-sleep VALUE 指数バックオフを使用した再試行ループで Cloud Storage FUSE がスリープできる最大時間を指定します。値は時間の長さである必要があります。たとえば、1h5m50s（1 時間 5 分 50 秒）または 60s（60 秒）です。バックオフ時間が指定の最大時間を超えると、指定された最大時間で再試行が続行されます。デフォルト値は 30s です。
--metadata-cache-ttl-secs VALUE

キャッシュに保存されたメタデータ エントリの有効期間（TTL）を秒単位で指定します。

  • TTL の有効期限をバイパスし、キャッシュから利用可能な場合にファイルを配信するには、-1 の値を指定します。
  • 最新のファイルを使用するには、0 の値を指定します。この値を使用すると、Get メタデータ呼び出しが行われ、キャッシュ内のファイルのオブジェクトの世代が Cloud Storage に保存されているものと一致していることを確認します。詳細については、キャッシュの無効化の構成をご覧ください。

このフィールドを省略した場合、デフォルト値の 60（60 秒）が使用されます。
-o VALUE

追加のシステム固有のマウント オプションを指定します。

FUSE のほとんどの汎用マウント オプション（suid など）は Cloud Storage FUSE でサポートされており、-o フラグとともに渡すことができます。

-o フラグで使用できる一般的なマウント オプションには、次のようなものがあります。

  • rw: 読み取り / 書き込みとしてマウントします。
  • ro: 読み取り専用としてマウントします。

サポートされているその他のマウント オプションの詳細については、Linux FUSE のドキュメントをご覧ください。
--only-dir VALUE バケット内の特定のディレクトリのみをマウントします。
--rename-dir-limit VALUE 指定した上限よりも子孫の少ないディレクトリの名前を変更できます。値は 0～2147483647 の範囲で指定してください。デフォルトの上限値は 0 です。
--retry-multiplier VALUE 連続する再試行間の指数バックオフの乗数を指定します。値は浮動小数点数で指定する必要があります。デフォルト値は 2 です。
--reuse-token-from-url --token-url から取得したトークンを再利用するかどうかを指定します。デフォルト値は true です。
--sequential-read-size-mb VALUE Cloud Storage からダウンロードするデータのチャンクサイズをメガバイト（MB）単位で指定します。値は 1～1024 の範囲で指定してください。デフォルト値は 200 です。
--stackdriver-export-interval VALUE 指定した間隔で指標を Stackdriver にエクスポートします。値は時間である必要があります。例: 1h10m10sデフォルト値は 0s です。これはエクスポートを指定しません。
--stat-cache-capacity VALUE 非推奨。統計情報キャッシュが保持できるエントリ数を指定します。これはメモリ消費に影響します。値には整数を指定してください。デフォルト値は 4096 です。

このフラグは --stat-cache-max-size-mb に置き換えられました。統計情報キャッシュで使用できる最大サイズ（MiB）を指定するには、--stat-cache-max-size-mb フラグを使用します。
--stat-cache-max-size-mb VALUE

統計情報キャッシュで使用できる最大サイズ（MiB）。統計情報キャッシュは常にメモリ内に保持されます。

  • ワークロードに最大 20,000 個のファイルが含まれる場合は、32 の値を指定します。ワークロードのファイル数が 20,000 を超える場合は、6,000 ファイルを追加するごとにサイズを 10 ずつ増やします。統計キャッシュはファイルあたり平均 1,500 MiB を使用します。
  • 統計情報キャッシュが必要なだけメモリを使用できるようにするには（つまり上限を設定しない場合は）、値 -1 を指定します。
  • 統計情報キャッシュを無効にするには、値 0 を指定します。

このフィールドを省略した場合、デフォルト値の 32 が使用されます。
--stat-cache-ttl VALUE 非推奨。StatObject の結果と i ノード属性をキャッシュに保存する期間を指定します。デフォルト値は 60s（60 秒）です。

このフラグは --metadata-cache-ttl-secs に置き換えられました。キャッシュに保存されたメタデータ エントリの有効期間（TTL）を秒単位で指定するには、--metadata-cache-ttl-secs フラグを使用します。
--temp-dir VALUE Cloud Storage にアップロードする前に書き込みがステージングされる一時ディレクトリのパスを指定します。デフォルト値はシステムのデフォルトです（多くの場合、/tmp）。
--token-url VALUE --key-file が存在しない場合にアクセス トークンを取得するための URL を指定します。
--type-cache-ttl VALUE 非推奨。ディレクトリの i ノード内の名前とファイルまたはディレクトリ間のマッピングをキャッシュに保存する期間を指定します。このオプションは --metadata-cache-ttl-secs オプションに置き換えられました。タイプ キャッシュに設定する時間を指定するには、--metadata-cache-ttl-secs オプションを使用します。このオプションは、統計情報キャッシュとタイプ キャッシュの両方のメタデータ エントリの有効期間（TTL）を指定します。--metadata-cache-ttl-secs のデフォルト値は 60s（60 秒）です。
--type-cache-max-size-mb VALUE

タイプ キャッシュが使用できるディレクトリあたりの最大サイズ（MiB 単位）。タイプ キャッシュは常にメモリ内に保持されます。

  • マウントするバケットの 1 つのディレクトリにあるファイルの最大数が 20,000 以下の場合は、値 4 を指定します。マウントする 1 つのディレクトリ内のファイルの最大数が 20,000 を超える場合は、5,000 ファイルごとに値を 1 増やします（ファイルあたり平均約 200 バイト）。
  • タイプ キャッシュが必要なだけメモリを使用できるようにするには（つまり上限を指定しない場合は）、値 -1 を指定します。
  • タイプ キャッシュを無効にするには、値 0 を指定します。

このフィールドを省略した場合、デフォルト値の 4 が使用されます。
--uid VALUE すべての i ノードのユーザー識別子（UID）所有者を指定します。値には整数を指定してください。デフォルトの UID 値は -1 です。