systemdのUnitファイルを読んだり書いたりしていると、
特定の設定項目について、どこに正確な説明があるのか分からず困ることがあります。

実はUnitファイルの設定項目は、ユニット種別ごとに1ページにまとまっているわけではなく、
複数のmanページに階層的に分散して記述されています。

本記事では、この階層構造を踏まえて公式マニュアルの読み方を整理します。

なお、この記事はsystemdのUnitファイルを編集した経験がある人を想定読者としています。

## systemd Unitファイルの公式仕様はmanページにある

systemdのUnitファイルの仕様や設定項目は、公式には`man`コマンドで表示されるマニュアルに集約されています。  

例えば、Unitファイル全体の共通仕様は次のコマンドで確認できます。

```bash
man systemd.unit
```

Web版は、systemdの開発主体が以下のサイトで公開しています。

https://www.freedesktop.org/software/systemd/man/latest/systemd.unit.html

> 注意：systemdのバージョンによって、ユニット種別や設定項目に違いがあります。
> このリンク先は最新バージョンのマニュアルを指しているため、お手元の環境と違いがある場合は`man`コマンドを優先してください。

## マニュアルの読み方のポイント

systemdのmanページは情報量が多く、設定項目がどのページにあるのか分かりにくい構成になっています。
そこで「設定項目がどの層に属するか」を意識して読むと見通しが良くなります。

### マニュアルの「3層構造」

Unitファイルの設定項目などは、概念的には次の3層に分けられます。

- 第一層：全Unit共通の仕様（systemd.unit）と記法（systemd.syntax）
- 第二層：複数Unit種別で共有される設定（systemd.exec、systemd.kill、systemd.resource-control）
- 第三層：Unit種別固有の設定（systemd.service、systemd.timer、systemd.socketなど）

### マニュアルの索引：systemd.directives

「設定項目名は分かるが、どのマニュアルに載っているか分からない」ときは、索引を活用します。

`man systemd.directives`コマンドで表示される
[systemd.directives](https://www.freedesktop.org/software/systemd/man/latest/systemd.directives.html)は索引ページに相当し、
全ての設定項目名と、それが記載されているページが一覧になっています。

このページを開いて項目名で検索するとどのページに説明があるかが分かります。

### （Tips）「Additional options…」の誘導を鍵にページをたどる

systemdのマニュアルでは、ページ冒頭付近に

> Additional options are listed in …

という文が書かれていることがあります。  
これは「このページに載っていない設定項目は、別のどのページに書かれているか」を示す案内です。  
設定が見つからない場合は、ページ内でこの一文を検索し、リンクされているページを確認すると効率的です。


## 各層の代表的なページの概略

### 第一層：全Unit共通の仕様（systemd.unit）と記法（systemd.syntax）

#### systemd.unit（共通の仕様）

- 対象：全てのUnit
- 主な内容：ユニットの説明文、依存関係、起動・有効化の条件
- 設定項目の例：`Description=`、`Requires=`、`After=`、`ConditionPathExists=`
- 主なセクション：`[Unit]`、`[Install]`

> 参考：Specifiers（`%i`や`%h`）についても、[systemd.unitのページの当該項目](https://www.freedesktop.org/software/systemd/man/latest/systemd.unit.html#Specifiers)に説明があります。

#### systemd.syntax（共通の記法）

- 対象：全てのUnit
- 主な内容：基本的な構文、エスケープ処理、コメントの書き方

> 参考：systemd.timerで使う時間関連（`48hr`や`Wed *-1`）の書き方はsystemd.timeのページです。

### 第二層：複数Unit種別で共有される設定

第二層の設定の特徴は、「記述するセクション」と「説明が書かれているmanページ」が一致しない点です。

例えば`User=`や`Environment=`は`[Service]`セクションに記述しますが、
説明はsystemd.serviceではなくsystemd.execのページにあります。

対して、第三層の設定（例：`ExecStart=`）は、
「記述するセクション（`[Service]`）」と「説明ページ（systemd.service）」が一致しています。

> 注意：以下の第二層の説明において、対象として例示しているユニットはsystemdのバージョンによっては違いがあります。

#### systemd.exec（実行環境全般）

- 対象：プロセスの実行に関わるユニット。例：service、socket、swap、mount
- 主な内容：実行ユーザ、環境変数、標準出力、作業ディレクトリ
- 設定項目の例：`User=`、`Environment=`、`StandardOutput=`、`WorkingDirectory=`

#### systemd.kill（停止時の制御）

- 対象：プロセスを持つユニット。例：scope、service、socket、swap、mount
- 主な内容：kill方法、タイムアウト時の挙動
- 設定項目の例：`KillMode=`、`KillSignal=`

#### systemd.resource-control（リソース制御）

- 対象：リソースを使用するユニット。例：slice、scope、service、socket、swap、mount
- 主な内容：CPU、メモリ、I/Oなどの制限
- 設定項目の例：`CPUQuota=`、`MemoryMax=`、`IOWeight=`、`TasksMax=`

### 第三層：Unit種別固有の設定

#### systemd.service（serviceユニット固有）

- 主な内容：起動方式、再起動、プロセス種別
- 設定項目の例：`ExecStart=`、`Restart=`、`Type=`、`PIDFile=`
- 主なセクション：`[Service]`

#### systemd.socket（socketユニット固有）

- 主な内容：待ち受けストリーム、モード、ユーザ・グループ
- 設定項目の例：`ListenStream=`、`SocketMode=`、`SocketUser=`
- 主なセクション：`[Socket]`

など

## 例：serviceユニットの書き方を調べる場合

`.service`ファイルについて読み書きする際は、以下の手順でマニュアルを参照します。

### 全体像を把握するとき

- 第一層（systemd.unit、systemd.syntax）で全Unitの共通事項を把握する
- 第二層（systemd.exec、systemd.kill、systemd.resource-control）で利用可能な共通設定を確認する
- 第三層（systemd.service）でserviceユニット固有の設定を確認する

### 設定項目名だけ分かっているとき

既存の`.service`を読む場合などで、特定の設定項目について調べたいときは、
systemd.directivesを開いてその設定項目名で検索します。
該当ページが分かれば、そこから詳細な仕様を確認できます。