はじめに
NASの共有フォルダをDockerコンテナにマウントし、コンテナ内のアプリケーションからファイルを参照しようとしたところ、Permission denied が発生しました。
NAS側にはACLによるアクセス制限があったため、専用グループを作成し、Docker Composeの group_add でそのグループを追加しました。
実際に docker exec で確認するとファイルを読み取れるようになったのですが、アプリケーション経由では依然として Permission denied になります。
調査した結果、アプリケーションの起動時に s6-setuidgid によるユーザー切り替えが行われ、Dockerで追加した補助グループが失われていたことが原因でした。
この記事では、問題の切り分けから解決までをまとめます。
結論
今回の問題は、次の対応で解決しました。
- NAS側に読み取り専用のグループを作成し、ACLを設定する。
- Docker Composeの
group_addに、そのグループの数値GIDを指定する。 - コンテナ内の
/etc/groupにも同じGIDのグループを作成し、アプリケーションの実行ユーザーを所属させる。 - カスタムDockerイメージを作成し、設定を恒久化する。
ポイントは3番目です。
group_add を設定しただけでは、コンテナ内のすべてのプロセスで補助グループが維持されるとは限りません。
特に、プロセスの起動途中でユーザー切り替えを行っている場合は、実際にファイル操作を行うプロセスの補助グループを確認する必要があります。
環境
今回の環境は、概ね次の構成でした。
- NAS:Synology DSM
- コンテナ:Docker / Docker Compose
- アプリケーション:Hermes Agent
- プロセス管理:s6-overlay
- ファイルアクセス:NASの共有フォルダをbind mount
- アプリケーション実行ユーザー:非rootユーザー
全体像は以下のとおりです。
NAS
├── 共有フォルダ(ACLでアクセス制御)
│
└── Docker
└── AIエージェントのコンテナ
├── ACPサーバー
├── Gateway
│ └── terminalツール
│
└── /workspace
└── NAS共有フォルダをマウント
AIエージェントでは、外部からの要求を処理するプロセスと、実際にコマンドを実行するプロセスが分かれていました。
これが今回の切り分けで重要になります。
なお、以下のGIDやコンテナ名は説明用に置き換えています。
1. 最初の問題:共有フォルダにアクセスできない
NASの共有フォルダを、次のようにDockerコンテナへ読み取り専用でマウントしました。
services:
agent:
image: example/agent:latest
volumes:
- /path/to/shared-folder:/workspace:ro
コンテナから /workspace は認識できましたが、ファイルを読み取ろうとするとアクセス拒否になります。
Permission denied
マウント自体は成功しているため、次に権限を調べました。
NASのACLを確認
Synology DSMでは共有フォルダのアクセス権限にACLが使用されています。
そのため、通常のLinuxパーミッションだけを確認しても、アクセスできない理由が分からない場合があります。
ACLの確認には、例えば次のコマンドが利用できます。
sudo /usr/syno/bin/synoacltool -get /path/to/shared-folder
調査したところ、NAS側でアクセスを許可されているユーザーと、コンテナ内のアプリケーション実行ユーザーのUID/GIDが一致していませんでした。
そこで、NAS側にアプリケーション専用の読み取りグループを用意することにしました。
2. 専用グループとDockerのgroup_addでアクセスを許可
NAS側に、例として次のグループを作成します。
グループ名:agent-readers
GID:60000
共有フォルダに、このグループの読み取り権限を設定します。
次に、Docker Composeへ group_add を追加します。
services:
agent:
image: example/agent:latest
group_add:
- "60000"
volumes:
- /path/to/shared-folder:/workspace:ro
ここで使用している 60000 は説明用です。実際にはNAS側で作成したグループのGIDを指定します。
動作確認
同じイメージを使った一時コンテナで、補助グループを付与した場合と付与しない場合を比較しました。
| 条件 | 結果 |
|---|---|
| 補助グループなし | Permission denied |
| 補助グループあり | 読み取り成功 |
Dockerで指定した補助グループを使えば、NASのACLを通過できることが確認できました。
ここまでは想定どおりです。
3. しかし、アプリケーション経由では依然としてPermission denied
問題はここからでした。
Dockerの補助グループを設定してコンテナを再作成した後、次のように直接コマンドを実行するとファイルを読み取れました。
docker exec -u 10000:10000 agent-container \
head -n 10 /workspace/sample.txt
ところが、AIエージェントに同じファイルの読み取りを指示すると、依然としてアクセス拒否になります。
つまり、次の状態です。
| 実行方法 | ファイル読み取り |
|---|---|
docker exec による直接実行 |
成功 |
| アプリケーションのファイル操作ツール | 失敗 |
この段階ではNAS側のACLを疑っていたのですが、直接実行で成功する以上、単純なACL設定の問題ではなさそうです。
そこで、実際にファイルを読み取っているプロセスの権限を調べることにしました。
4. プロセスごとに補助グループを調べる
Linuxでは、プロセスの状態を /proc/<PID>/status から確認できます。
grep -E '^(Name|Pid|PPid|Uid|Gid|Groups):' \
/proc/<PID>/status
Groups に、そのプロセスが持つ補助グループが表示されます。
例えば、期待していたのは次の状態です。
Uid: 10000 10000 10000 10000
Gid: 10000 10000 10000 10000
Groups: 10000 60000
しかし、各プロセスを確認してみると、違いが見つかりました。
| プロセス | 補助グループ |
|---|---|
| Docker execで起動したプロセス | 10000, 60000 |
| ACPサーバー | 10000, 60000 |
| Gateway | 10000 |
| terminalツール | 10000 |
なんと、Gatewayだけ補助グループ60000を持っていませんでした。
さらに調査すると、ファイル操作を行うterminalツールはGatewayの子プロセスとして起動されていました。
つまり、構造は次のようになっていたわけです。
Dockerコンテナ
│
├── ACPサーバー
│ └── Groups: 10000, 60000
│
└── Gateway
└── Groups: 10000
│
└── terminalツール
└── Groups: 10000
これで、直接コマンドを実行できるのにアプリケーションからは読み取れない理由が見えてきました。
5. 原因はs6-setuidgidによるユーザー切り替え
次に、Gatewayの起動方法を調査しました。
今回使用したコンテナは、サービス管理にs6-overlayを利用していました。
Gatewayの起動スクリプトでは、次のような処理が実行されていました。
exec s6-setuidgid hermes hermes gateway run --replace
s6-setuidgid は、指定されたユーザーでプログラムを実行するためのコマンドです。
このユーザー切り替えによって補助グループが再設定されていました。
ところが、コンテナ内の /etc/group を確認すると、NASで追加した専用グループのGIDが登録されていません。
そのため、今回の環境では次のことが起こっていました。
Dockerが補助グループを追加
Groups: 10000, 60000
│
▼
s6-setuidgidでユーザーを切り替え
│
▼
コンテナのグループ情報に
GID 60000の登録がない
│
▼
補助グループが再設定される
Groups: 10000
│
▼
アプリケーションからのアクセス失敗
Dockerの group_add に問題があったわけではありません。
コンテナ内部で実行されるユーザー切り替え処理によって、補助グループが維持されなかったというのが原因でした。
6. コンテナ内のグループ登録で解決
原因が判明したため、一時コンテナを使って解決方法を検証しました。
実行したのは次の処理です。
groupadd -g 60000 agent-readers
usermod -aG agent-readers hermes
これにより、コンテナ内にGID 60000のグループを登録し、実行ユーザーを所属させます。
続いて、実際の起動方法と同じ s6-setuidgid を使って確認しました。
/package/admin/s6/command/s6-setuidgid hermes id
グループ登録前は、補助グループが消えていました。
uid=10000(hermes)
gid=10000(hermes)
groups=10000(hermes)
登録後は、期待するグループが維持されました。
uid=10000(hermes)
gid=10000(hermes)
groups=10000(hermes),60000(agent-readers)
さらに、同じユーザー切り替え処理を通してNAS上のファイルを読み取るテストも実施し、成功することを確認しました。
カスタムDockerイメージで恒久化
この修正を恒久的に適用するため、公式イメージをベースとしたDockerfileを作成しました。
FROM nousresearch/hermes-agent:latest
USER root
RUN groupadd -g 60000 agent-readers \
&& usermod -aG agent-readers hermes
これは今回の環境で有効だった修正を一般化した例です。別のイメージではユーザー名、既存GID、起動方法などを確認してから適用する必要があります。
ビルド後、Docker Composeのイメージ指定をカスタムイメージに変更します。
services:
agent:
image: my-agent:group-access
group_add:
- "60000"
volumes:
- /path/to/shared-folder:/workspace:ro
再起動後、Gatewayのプロセスで補助グループが維持されていることを確認しました。
そして、AIエージェント経由でもNAS上のファイルを正常に読み取れるようになりました。
7. 同じ問題に遭遇した場合の切り分け方
今回の経験から、Dockerコンテナでアクセス権限の問題が起きた場合は、次の順番で調べるとよいと感じました。
① マウントが正しいか
docker inspect agent-container \
--format '{{json .Mounts}}'
ファイルやディレクトリが存在しない問題なのか、権限による問題なのかを切り分けます。
② 実行ユーザーを確認する
docker exec -u 10000:10000 agent-container id
UID、GID、補助グループを確認します。
③ 直接読み取れるか確認する
docker exec -u 10000:10000 agent-container \
head -n 10 /workspace/sample.txt
直接実行で成功するのにアプリケーションから失敗するなら、実行プロセスの違いを疑います。
④ 実際のプロセスのGroupsを確認する
grep -E '^(Name|Pid|PPid|Uid|Gid|Groups):' \
/proc/<PID>/status
親プロセスと子プロセスで補助グループが異ならないか確認します。
⑤ 起動時のユーザー切り替えを調べる
例えば、以下のような処理がないか確認します。
s6-setuidgidsurunuser- その他の権限変更処理
ユーザー切り替え時に補助グループがどのように設定されるかは、使用する仕組みによって異なります。
8. 補足:権限設定は必要最小限に
今回の環境では、NASの共有フォルダを読み取り専用でマウントしました。
volumes:
- /path/to/shared-folder:/workspace:ro
AIエージェントにファイル操作を許可する場合、最初から書き込み権限を与える必要はありません。
また、権限エラーを解決するために chmod -R 777 のような方法を使うと、本来制限すべきユーザーにもアクセスを許してしまう可能性があります。
今回のように専用グループを作成し、必要な権限だけを割り当てる方が、管理しやすいと考えています。
なお、カスタムDockerイメージを作成する場合は、.dockerignore に認証情報や実行時データの除外設定を追加することも重要です。
まとめ
今回の問題は、次のような流れで解決しました。
- NASの共有フォルダにアクセスできないため、ACLを確認した。
- 専用グループとDockerの
group_addによって、コンテナから直接ファイルを読めるようになった。 - しかし、アプリケーション経由では
Permission deniedが続いた。 - プロセスごとの補助グループを確認したところ、Gatewayだけ追加グループを持っていなかった。
-
s6-setuidgidによるユーザー切り替えが原因と判明した。 - コンテナ内にもグループを登録し、実行ユーザーを所属させることで解決した。
今回の一番の教訓は、Dockerコンテナの権限と、実際に動作しているプロセスの権限は、必ずしも同じではないということです。
group_add を設定しているのにファイルが読めない場合、NASのACLやDockerの設定を繰り返し変更する前に、実際にファイルを操作しているプロセスの Groups を確認してみると、原因を特定できるかもしれません。
この記事は、Synology NASとHermes Agentを使用した実際の構築・検証結果を基にしています。掲載したパスやGIDなどの一部は一般化しています。s6-overlayの設定やユーザー切り替え方式は、コンテナイメージやバージョンによって異なる場合があります。