From: KATOH Yasufumi <karma@jazz.email.ne.jp>
Date: Sun, 27 Jun 2021 15:10:09 +0000 (+0900)
Subject: doc: Add eBPF-based device controller semantics to Japanese man page
X-Git-Tag: lxc-5.0.0~144^2~3
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=5793ff9bd2233822832d8b3ff926650502ce990b;p=thirdparty%2Flxc.git

doc: Add eBPF-based device controller semantics to Japanese man page

Update for commit 5025f3a69053bbddbe6c76ffb55b4bbd5759dcc8

Signed-off-by: KATOH Yasufumi <karma@jazz.email.ne.jp>
---

diff --git a/doc/ja/lxc.container.conf.sgml.in b/doc/ja/lxc.container.conf.sgml.in
index 190bcecce..60ffd8c99 100644
--- a/doc/ja/lxc.container.conf.sgml.in
+++ b/doc/ja/lxc.container.conf.sgml.in
@@ -2027,7 +2027,7 @@ by KATOH Yasufumi <karma at jazz.email.ne.jp>
     </refsect2>
 
     <refsect2>
-      <title>Control group</title>
+      <title>Control group ("cgroup")</title>
       <para>
         <!--
         The control group section contains the configuration for the
@@ -2041,10 +2041,281 @@ by KATOH Yasufumi <karma at jazz.email.ne.jp>
         <command>lxc</command> は、このサブシステム名の正しさはチェックしません。
         実行時のエラーを検出するのに不便ですが、別の将来のサブシステムをサポート出来るという有利な点もあります。
       </para>
+
+      <para>
+        <!--
+        The kernel implementation of cgroups has changed significantly over the
+        years. With Linux 4.5 support for a new cgroup filesystem was added
+        usually referred to as "cgroup2" or "unified hierarchy". Since then the
+        old cgroup filesystem is usually referred to as "cgroup1" or the
+        "legacy hierarchies". Please see the cgroups manual page for a detailed
+        explanation of the differences between the two versions.
+          -->
+        カーネルにおける cgroup 実装は長年にわたって大きく変化してきました。
+        Linux 4.5 で新しい cgroup ファイルシステムのサポートが追加されました。通常は "cgroup2" や "unified hierarchy"（単一階層構造） と呼ばれています。
+        それ以来、通常は古い cgroup ファイルシステムは "cgroup1" や "legacy hierarchies"（レガシー階層構造）と呼ばれています。
+        この 2 つのバージョンの違いについての詳細な説明は、cgroup のマニュアルページをご覧ください。
+      </para>
+
+      <para>
+        <!--
+        LXC distinguishes settings for the legacy and the unified hierarchy by
+        using different configuration key prefixes. To alter settings for
+        controllers in a legacy hierarchy the key prefix
+        <option>lxc.cgroup.</option> must be used and in order to alter the
+        settings for a controller in the unified hierarchy the
+        <option>lxc.cgroup2.</option> key must be used. Note that LXC will
+        ignore <option>lxc.cgroup.</option> settings on systems that only use
+        the unified hierarchy. Conversely, it will ignore
+        <option>lxc.cgroup2.</option> options on systems that only use legacy
+        hierachies.
+        -->
+        LXC は cgroup1（レガシー階層構造）と cgroup2（単一階層構造）に対する設定を、異なる設定プレフィックスを使って区別しています。
+        cgroup1 に対する設定を変更するには <option>lxc.cgroup.</option> というプレフィックスを使う必要があり、cgroup2 の設定を変更するには <option>lxc.cgroup2.</option> を使う必要があります。
+        LXC は、cgroup2 だけが使われているシステム上の <option>lxc.cgroup.</option> を無視します。逆に cgroup1 だけが使われているシステム上の <option>lxc.cgroup2.</option> を無視します。
+      </para>
+
+      <para>
+        <!--
+        At its core a cgroup hierarchy is a way to hierarchically organize
+        processes. Usually a cgroup hierarchy will have one or more
+        "controllers" enabled. A "controller" in a cgroup hierarchy is usually
+        responsible for distributing a specific type of system resource along
+        the hierarchy. Controllers include the "pids" controller, the "cpu"
+        controller, the "memory" controller and others. Some controllers
+        however do not fall into the category of distributing a system
+        resource, instead they are often referred to as "utility" controllers.
+        One utility controller is the device controller. Instead of
+        distributing a system resource it allows to manage device access.
+        -->
+        cgroup 階層の本質は、プロセスを階層的に構造化する方法です。通常は、cgroup 階層では 1 つ以上の「コントローラー」が有効になっています。
+        通常、cgroup 階層の「コントローラー」は階層に従って特定のタイプのシステムリソースを分配する役割を果たします。
+        コントローラーには "pids" コントローラー、"cpu" コントローラー、"memory" コントローラーなどがあります。
+        しかし、システムリソースの分配するという役割に該当しないコントローラーもあります。このようなコントローラーは「ユーティリティー」コントローラーと呼ばれたりします。
+        ユーティリティーコントローラーの 1 つにデバイスコントローラーがあります。このコントローラーはシステムリソースを分配する代わりにデバイスへのアクセスを管理できます。
+      </para>
+
+      <para>
+        <!--
+        In the legacy hierarchy the device controller was implemented like most
+        other controllers as a set of files that could be written to. These
+        files where named "devices.allow" and "devices.deny". The legacy device
+        controller allowed the implementation of both "allowlists" and
+        "denylists".
+        -->
+        cgroup1 では、デバイスコントローラーは他の多くのコントローラーと同様に、書き込みできるファイルのセットとして実装されていました。
+        これらのファイルは "devices.allow" と "devices.deny" という名前のファイルでした。レガシーデバイスコントローラーは「許可リスト（allowlists）」と「拒否リスト（denylists）」の両方を実装できました。
+      </para>
+
+      <para>
+        <!--
+        An allowlist is a device program that by default blocks access to all
+        devices. In order to access specific devices "allow rules" for
+        particular devices or device classes must be specified. In contrast, a
+        denylist is a device program that by default allows access to all
+        devices. In order to restrict access to specific devices "deny rules"
+        for particular devices or device classes must be specified.
+        -->
+        許可リスト（allowlist）とは、すべてのデバイスへのアクセスをブロックするデバイスプログラムです。特定のデバイスへのアクセスを行うには、特定のデバイスもしくはデバイスクラスに対する「許可ルール（allow rules）」を指定する必要があります。
+        一方、拒否リスト（denylist）はデフォルトですべてのデバイスへのアクセスを許可するデバイスプログラムです。特定のデバイスへのアクセスを拒否するには、特定のデバイスもしくはデバイスクラスに対する「拒否ルール（deny rules）」を指定する必要があります。
+      </para>
+
+      <para>
+        <!--
+        In the unified cgroup hierarchy the implementation of the device
+        controller has completely changed. Instead of files to read from and
+        write to a eBPF program of
+        <option>BPF_PROG_TYPE_CGROUP_DEVICE</option> can be attached to a
+        cgroup. Even though the kernel implementation has changed completely
+        LXC tries to allow for the same semantics to be followed in the legacy
+        device cgroup and the unified eBPF-based device controller. The
+        following paragraphs explain the semantics for the unified eBPF-based
+        device controller.
+        -->
+        cgroup2 では、デバイスコントローラーの実装が完全に変わりました。読み書きするファイルの代わりに、<option>BPF_PROG_TYPE_CGROUP_DEVICE</option> の eBPF プログラムを cgroup にアタッチできます。
+        カーネルの実装が完全に変わったのにもかかわらず、LXC は cgroup1 のデバイスコントローラーと cgroup2 の eBPF ベースのデバイスコントローラーで同じセマンティクスに従えるようにしています。
+        このあとの段落では、cgroup2 の eBPF デバイスコントローラーに対するセマンティクスを説明します。
+      </para>
+
+      <para>
+        <!--
+        As mentioned the format for specifying device rules for the unified
+        eBPF-based device controller is the same as for the legacy cgroup
+        device controller; only the configuration key prefix has changed.
+        Specifically, device rules for the legacy cgroup device controller are
+        specified via <option>lxc.cgroup.devices.allow</option> and
+        <option>lxc.cgroup.devices.deny</option> whereas for the
+        cgroup2 eBPF-based device controller
+        <option>lxc.cgroup2.devices.allow</option> and
+        <option>lxc.cgroup2.devices.deny</option> must be used.
+        -->
+        先に述べたように、cgroup2 の eBPF ベースのデバイスコントローラーに対するデバイスルールを指定するフォーマットは、cgroup1 のデバイスコントローラーと同じです。ただし、設定キーのプレフィックスは変更されています。
+        具体的には、cgroup1 のデバイスコントローラーに対するデバイスルールは <option>lxc.cgroup.devices.allow</option> と <option>lxc.cgroup.devices.deny</option> を使って指定します。一方、cgroup2 の eBPF ベースのコントローラーでは <option>lxc.cgroup2.devices.allow</option> と <option>lxc.cgroup2.devices.deny</option> を使わなければなりません。
+      </para>
+      <para>
+        <itemizedlist>
+          <listitem>
+            <para>
+              <!--
+              A allowlist device rule
+              <programlisting>
+                lxc.cgroup2.devices.deny = a
+              </programlisting>
+              will cause LXC to instruct the kernel to block access to all
+              devices by default. To grant access to devices allow device rules
+              must be added via the <option>lxc.cgroup2.devices.allow</option>
+              key. This is referred to as a "allowlist" device program.
+              -->
+              許可リスト（allowlist）のデバイスルール
+              <programlisting>
+                lxc.cgroup2.devices.deny = a
+              </programlisting>
+              は、カーネルに対してデフォルトですべてのデバイスへのアクセスをブロックするように LXC が指示します。
+              デバイスへのアクセスを許可するには、デバイスに対する許可ルールを <option>lxc.cgroup2.devices.allow</option> を使って追加する必要があります。これは「許可リスト」デバイスプログラムとして参照されます。
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              <!--
+              A denylist device rule
+              <programlisting>
+                lxc.cgroup2.devices.allow = a
+              </programlisting>
+              will cause LXC to instruct the kernel to allow access to all
+              devices by default. To deny access to devices deny device rules
+              must be added via <option>lxc.cgroup2.devices.deny</option> key.
+              This is referred to as a "denylist" device program.
+              -->
+              拒否リスト（denylist）のデバイスルール
+              <programlisting>
+                lxc.cgroup2.devices.allow = a
+              </programlisting>
+              は、カーネルに対してすべてのデバイスへのアクセスをデフォルトで許可するように LXC が指示します。
+              デバイスへのアクセスを拒否するには、デバイスに対する拒否ルールを <option>lxc.cgroup2.devices.deny</option> を使って追加する必要があります。これは「拒否リスト」デバイスプログラムとして参照されます。
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              <!--
+              Specifying any of the aformentioned two rules will cause all
+              previous rules to be cleared, i.e. the device list will be reset.
+              -->
+              前述の 2 つのルールのいずれかを指定すると、それ以前に指定していたルールがすべてクリアされます。つまり、デバイスリストがリセットされます。
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              <!--
+            When an allowlist program is requested, i.e. access to all devices
+            is blocked by default, specific deny rules for individual devices
+            or device classes are ignored.
+                -->
+              許可リストプログラムが要求される場合、つまりデフォルトですべてのデバイスへのアクセスがブロックされている場合、個別のデバイスやデバイスクラスへの拒否ルールを指定しても無視されます。
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              <!--
+            When a denylist program is requested, i.e. access to all devices
+            is allowed by default, specific allow rules for individual devices
+            or device classes are ignored.
+                -->
+              拒否リストプログラムが要求される場合、つまりデフォルトですべてのデバイスへのアクセスが許可されている場合、個別のデバイスやデバイスクラスへの許可ルールを指定しても無視されます。
+            </para>
+          </listitem>
+        </itemizedlist>
+      </para>
+
+      <para>
+        <!--
+        For example the set of rules:
+          -->
+        例えば、次のようなルールの組
+        <programlisting>
+          lxc.cgroup2.devices.deny = a
+          lxc.cgroup2.devices.allow = c *:* m
+          lxc.cgroup2.devices.allow = b *:* m
+          lxc.cgroup2.devices.allow = c 1:3 rwm
+        </programlisting>
+        <!--
+        implements an allowlist device program, i.e. the kernel will block
+        access to all devices not specifically allowed in this list. This
+        particular program states that all character and block devices may be
+        created but only /dev/null might be read or written.
+          -->
+        は、許可リスト（allowlist）デバイスプログラムを実装します。つまり、カーネルはこのリストで許可されるように設定されていないすべてのデバイスへのアクセスをブロックします。
+        このプログラムでは、すべてのキャラクターデバイスとブロックデバイスが作成できますが、読み書きは /dev/null に対してしか行なえません。
+      </para>
+
+      <para>
+        <!--
+        If we instead switch to the following set of rules:
+          -->
+        代わりに先のルールから次のようなルールの組に変更したとすると、
+        <programlisting>
+          lxc.cgroup2.devices.allow = a
+          lxc.cgroup2.devices.deny = c *:* m
+          lxc.cgroup2.devices.deny = b *:* m
+          lxc.cgroup2.devices.deny = c 1:3 rwm
+        </programlisting>
+         <!--
+         then LXC would instruct the kernel to implement a denylist, i.e. the
+         kernel will allow access to all devices not specifically denied in
+         this list. This particular program states that no character devices or
+         block devices might be created and that /dev/null is not allow allowed
+         to be read, written, or created.
+           -->
+        LXC はカーネルに拒否リスト（denylist）の実装を指示します。つまりカーネルはこのリストで拒否を指定していないすべてのデバイスへのアクセスを許可します。
+        このプログラムでは、キャラクターデバイスとブロックデバイスは作成できません。そして /dev/null の読み書きと作成は許可されません。
+      </para>
+
+      <para>
+        <!--
+         Now consider the same program but followed by a "global rule"
+         which determines the type of device program (allowlist or
+         denylist) as explained above:
+          -->
+        ここで、同じプログラムでも、前述のようにデバイスのプログラムタイプを決定するような「グローバルルール」が続いている場合を考えてみましょう。
+        <programlisting>
+          lxc.cgroup2.devices.allow = a
+          lxc.cgroup2.devices.deny = c *:* m
+          lxc.cgroup2.devices.deny = b *:* m
+          lxc.cgroup2.devices.deny = c 1:3 rwm
+          lxc.cgroup2.devices.allow = a
+        </programlisting>
+        <!--
+        The last line will cause LXC to reset the device list without changing
+        the type of device program.
+          -->
+        最後の行は、デバイスプログラムのタイプを変更せずに、LXC がデバイスリストをリセットしてしまいます。
+      </para>
+
+      <para>
+        <!--
+        If we specify:
+          -->
+        次のように指定した場合、
+        <programlisting>
+          lxc.cgroup2.devices.allow = a
+          lxc.cgroup2.devices.deny = c *:* m
+          lxc.cgroup2.devices.deny = b *:* m
+          lxc.cgroup2.devices.deny = c 1:3 rwm
+          lxc.cgroup2.devices.deny = a
+        </programlisting>
+        <!--
+        instead then the last line will cause LXC to reset the device list and
+        switch from a allowlist program to a denylist program.
+          -->
+        前の例と違って最後の行によって、LXC はデバイスリストをリセットし、許可リスト（allowlist）から拒否リスト（denylist）にプログラムを変更してしまいます。
+      </para>
       <variablelist>
         <varlistentry>
           <term>
-            <option>lxc.cgroup.[control name]</option>
+            <option>lxc.cgroup.[control name].[controller file]</option>
           </term>
           <listitem>
             <para>
@@ -2056,7 +2327,7 @@ by KATOH Yasufumi <karma at jazz.email.ne.jp>
               kernel running at the time the container is started, eg.
               <option>lxc.cgroup.cpuset.cpus</option>
               -->
-              legacy な cgroup 階層 (cgroup v1) に設定する値を指定します。コントローラー名は control group そのままの名前です。
+              レガシー cgroup 階層 (cgroup v1) に設定する値を指定します。コントローラー名は control group そのままの名前です。
               許される名前や値の書式は LXC が指定することはなく、コンテナが実行された時に実行されている Linux カーネルの機能に依存します。
               例えば <option>lxc.cgroup.cpuset.cpus</option> のようになります。
             </para>
@@ -2064,7 +2335,7 @@ by KATOH Yasufumi <karma at jazz.email.ne.jp>
         </varlistentry>
         <varlistentry>
           <term>
-            <option>lxc.cgroup2.[controller name]</option>
+            <option>lxc.cgroup2.[controller name].[controller file]</option>
           </term>
           <listitem>
             <para>