systemd Unit設定値の意味と安全な設定方法
このページの目的：Unit適用前に、起動方法・依存関係・自動起動を確認し、サービス起動の失敗を防ぐ
このページで分かること
- Unitファイルの基本構成
- 設定例が実際にどう動くか
- 主要な設定値と指定できる値の意味
After=とRequires=の違い- 自動起動と
WantedBy=の関係 - 起動失敗・再起動ループの確認順
先に結論
Unitは「起動順序」「依存関係」「実行ユーザー」「プロセス種別」「再起動条件」を分けて設計します。適用前に systemd-analyze verify を実行し、変更後は daemon-reload と状態確認を行います。
Unitファイルをすぐ確認する
自分のUnitファイルを貼り付けて、起動失敗や再起動ループにつながる設定を実行前に確認できます。
問題がすでに起きている場合：すでにサービスが起動しない・failedになる場合は、専用のトラブル解決ガイドでstatusとjournalから切り分けられます。 トラブル解決ガイドを見る →
Unitファイルの基本構成
[Unit]
Description=Example application
After=network-online.target
Wants=network-online.target
[Service]
Type=simple
User=appuser
WorkingDirectory=/opt/example
ExecStart=/usr/bin/python3 /opt/example/app.py
Restart=on-failure
RestartSec=5s
[Install]
WantedBy=multi-user.target
| セクション | 役割 |
|---|---|
[Unit] | Unitの説明、起動順序、依存関係、起動条件を定義します。 |
[Service] | 実行コマンド、実行ユーザー、プロセス種別、再起動条件などを定義します。 |
[Install] | systemctl enable時に、どのtargetやUnitへ紐付けるかを定義します。 |
この設定例の動作： ネットワーク利用可能状態を示すtargetの後に、
appuserユーザーで/opt/exampleを作業ディレクトリとしてPythonアプリを起動します。異常終了した場合は5秒待って再起動します。systemctl enableを実行すると、通常のマルチユーザー起動時の自動起動対象になります。設定例を1行ずつ読む
| 設定例 | この例での動作 |
|---|---|
Description=Example application | systemctl statusなどに表示する説明名です。サービスの動作には直接影響しません。 |
After=network-online.target | network-online.targetより後に起動処理を開始します。起動順序のみの指定です。 |
Wants=network-online.target | このサービスを起動する際、network-online.targetも起動対象に加えます。弱い依存関係なので、対象の失敗が常にこのサービスの失敗になるわけではありません。 |
Type=simple | ExecStartで起動したプロセスをメインプロセスとして扱います。アプリはフォアグラウンドで動き続ける前提です。 |
User=appuser | rootではなくappuserとして実行します。実行ファイル、作業ディレクトリ、ログ出力先への権限が必要です。 |
WorkingDirectory=/opt/example | 起動時のカレントディレクトリを/opt/exampleにします。 |
ExecStart=/usr/bin/python3 /opt/example/app.py | Python 3でapp.pyを起動します。実行ファイルは絶対パスで指定しています。 |
Restart=on-failure | 終了コードが0以外の場合やシグナル、タイムアウトなどで失敗した場合に再起動します。正常終了時は再起動しません。 |
RestartSec=5s | 異常終了後、5秒待ってから再起動します。 |
WantedBy=multi-user.target | systemctl enable時にmulti-user.target.wants配下へリンクを作成します。 |
この例だけでは保証されないこと：
network-online.targetを指定しても、環境側のwait-onlineサービスが有効でなければ、実際の通信可能状態まで待たない場合があります。また、enableだけではその場で起動しないため、初回から起動するならsystemctl enable --now example.serviceを使います。主要な設定値（役割別）
Unitファイルは、設定名だけでなく「どの値を選ぶか」で動作が変わります。セクションごとに整理して確認します。
[Unit]：説明・起動順序・依存関係
| 設定 | 主な値・書き方 | 意味と注意点 |
|---|---|---|
Description= | 任意の説明文 | systemctl statusなどに表示される説明です。役割が分かる名前にします。 |
Documentation= | URL、man:、file: | 手順書や公式ドキュメントへの参照を指定します。複数指定できます。 |
After= | Unit名を空白区切り | 指定したUnitより後に起動する順序関係です。相手を自動起動する依存関係ではありません。 |
Before= | Unit名を空白区切り | 指定したUnitより先に起動する順序関係です。 |
Wants= | Unit名を空白区切り | 弱い依存関係です。相手を同時に起動対象へ加えますが、相手の失敗が必ずこのUnitの失敗になるわけではありません。 |
Requires= | Unit名を空白区切り | 強い依存関係です。必要なUnitを起動対象へ加えます。相手より後に起動させ、相手の起動失敗時にこちらを開始させたくない場合は、After=を併用します。相手が停止・非アクティブ化された場合は、こちらも停止対象になります。 |
ConditionPathExists= | 絶対パス | 対象パスが存在する場合だけ起動します。条件不成立は通常、失敗ではなくスキップとして扱われます。 |
[Service]：プロセスの起動方法
| 設定 | 主な値・書き方 | 意味と注意点 |
|---|---|---|
Type= | simple、exec、oneshot、forking、notify | simpleは起動コマンドを主プロセスとして扱います。execは実行ファイルの起動成功まで確認します。oneshotは短時間処理、forkingはfork型デーモン、notifyはアプリから準備完了通知を受ける方式です。 |
User= / Group= | OSユーザー名・グループ名 | サービスを実行する権限主体です。必要最小限の専用ユーザーを推奨します。 |
WorkingDirectory= | 絶対パス | 実行時のカレントディレクトリです。存在しない、または実行ユーザーが辿れないと起動に失敗します。 |
ExecStart= | 実行ファイルと引数 | サービス本体の起動コマンドです。実行ファイルは絶対パスで指定すると環境差を避けやすくなります。単純なファイル名はsystemdの固定検索パスから解決される場合がありますが、シェルのPATHやaliasは前提にできません。パイプやリダイレクトなどのシェル構文も通常そのまま解釈されません。 |
ExecStartPre= | 事前実行コマンド | ExecStart前の準備・検証です。失敗すると通常は本体を起動しません。 |
ExecReload= | 再読込コマンド | systemctl reload時に実行します。アプリが設定再読込に対応している場合に指定します。 |
ExecStop= | 停止コマンド | 正常停止用の処理です。未指定の場合はsystemdが主プロセスへ停止シグナルを送ります。 |
Environment= | KEY=value | 環境変数を直接指定します。秘密情報の直書きは避けます。 |
EnvironmentFile= | 環境変数ファイルの絶対パス | 外部ファイルから環境変数を読み込みます。先頭に-を付けると、ファイルがなくても起動を継続します。 |
Restart=で指定できる主な値
| 値 | 再起動する条件 | 使い分け |
|---|---|---|
no | 自動再起動しない | 既定値です。一回限りの処理や手動操作向けです。 |
on-success | 正常終了時 | 常駐サービスでは用途が限定的です。 |
on-failure | 異常終了、シグナル、タイムアウトなど | 一般的な常駐サービスで使いやすい値です。 |
on-abnormal | シグナルやタイムアウトなど | 終了コードによる通常の失敗では再起動しません。 |
on-abort | 未捕捉シグナルによる終了 | クラッシュ時だけ再起動したい場合に使います。 |
on-watchdog | watchdogタイムアウト | watchdog連携を構成しているサービス向けです。 |
always | 正常・異常を問わず終了時 | 正常終了でも再起動します。短時間で終了するコマンドでは再起動ループに注意します。 |
再起動・タイムアウト・出力
| 設定 | 例 | 意味 |
|---|---|---|
RestartSec= | 5s、30s | 再起動までの待機時間です。短すぎる値はログ急増や外部接続の連打につながります。 |
TimeoutStartSec= | 90s、infinity | 起動完了を待つ上限時間です。 |
TimeoutStopSec= | 30s | 正常停止を待つ上限時間です。超過すると強制終了へ進む場合があります。 |
KillSignal= | SIGTERM、SIGINT | 停止時に送る主なシグナルです。 |
SuccessExitStatus= | 1 2、SIGTERM | 通常は失敗扱いになる終了コードやシグナルを正常終了として扱います。 |
StandardOutput= / StandardError= | journal、null、append:/path | 標準出力・標準エラーの出力先です。まずはjournalへ集約すると切り分けしやすくなります。 |
[Install]：enable時の紐付け
| 設定 | 主な値 | 意味 |
|---|---|---|
WantedBy= | multi-user.targetなど | enable時に弱い依存関係として紐付けます。 |
RequiredBy= | target・Unit名 | enable時に強い依存関係として紐付けます。 |
Alias= | 別名のUnit名 | enable時に別名のシンボリックリンクを作成します。 |
バージョン差： 使用できる設定値はsystemdのバージョンによって異なります。対象環境では
man systemd.service、man systemd.unit、systemd-analyze verifyで確認してください。AfterとRequiresの違い
After=は起動順序、Wants=とRequires=は依存関係を指定します。順序と依存は別のため、必要に応じて組み合わせます。
詳しい比較： 障害時の挙動、典型的な組み合わせ、確認コマンドはAfter・Wants・Requiresの違いで確認できます。
WantedBy=multi-user.targetとは
WantedBy=multi-user.targetは、systemctl enable時に通常のマルチユーザー起動へUnitを紐付ける代表的な指定です。記述しただけでは自動起動は有効になりません。
仕組みを詳しく確認： enableで作成されるリンクやstart・enable・
--nowの違いはWantedBy=multi-user.targetとはで説明しています。問題発生時の案内
この作業ガイドは、Unitファイルを作成・変更する前の設計と確認を対象にしています。すでにサービスが起動しない場合は、ここで設定値を見直し続けるのではなく、状態・ログ・構文の順に切り分けます。
よくある失敗
ExecStartの引数で相対パスを使い、想定したカレントディレクトリから実行されると考える- 実行ユーザーがファイルや親ディレクトリへアクセスできない
- 環境変数やPATHをログインシェルと同じだと考える
Restart=alwaysと短いRestartSecで失敗を高速反復する- Unitを変更した後に
daemon-reloadしていない
再起動ループ： 原因を直さずに
Restart=alwaysを指定すると、ログ増加や外部サービスへの連続接続を招くことがあります。まず手動実行とjournalで失敗原因を確認します。関連するトラブル解決
systemctl enableしたのに自動起動しない場合は、enable状態、WantedBy、条件、依存関係、起動時ログを順番に確認します。
Unitファイルを実行前にレビュー
Unitを貼り付けて、相対パス、権限、依存関係、再起動設定などの注意点を確認できます。