Dev Utility JP

Linuxのsystemdサービス失敗・journalctlログを切り分ける手順

Linuxで「serviceが動かない」ときは、unitの状態、読み込まれた設定、終了結果、journal logを分けて確認します。一つの表示だけで原因を決めず、読み取り中心の結果を同じ時刻帯でそろえて次の調査対象を絞ります。

この手順はsystemdを使う環境が対象です。commandのpropertyや表示はsystemdのversion、unit type、権限によって異なるため、導入環境のman pageを優先します。原因確認と復旧操作を分け、serviceやunit fileの状態は変更しません。

最初に対象と時刻を記録する

次の例にあるexample.serviceは説明用です。実環境では、調査対象として許可された正確なunit名へ置き換えます。

system unitはsystem manager、user unitは現在のuserのservice managerを確認するため、以降は両方のcommandを分けて掲載します。対象の種類を確認して、対応する一方だけを実行してください。user unitにはsystemctl --userを使い、system unitと同名でも取り違えないようにします。

1. failed状態のunitを確認する

system unit:

systemctl --failed --no-pager

user unit:

systemctl --user --failed --no-pager

systemd managerに読み込まれているunitから、現在failed状態にあるものを確認します。一覧に対象があってもroot causeが確定したことにはならず、一覧にない場合も過去の失敗履歴やapplication-levelの異常がないとは断定できません。対象unitと観測時刻を記録して次へ進みます。

2. 対象serviceの現在状態と直近メッセージを確認する

system unit:

systemctl status example.service --no-pager -l

user unit:

systemctl --user status example.service --no-pager -l

systemctl statusは、対象unitのruntime状態とjournalの直近メッセージを人が読む形式で表示します。表示されるlogは一部であり、journal全履歴ではありません。以前の起動やすでにmanagerのmemoryから解放された状態は、対象unitのjournalと別に照合します。

inactiveやfailedなどserviceの状態によってcommandがnon-zeroで終了する場合があります。commandを実行できなかったことと、表示されたservice状態を混同せず、Active行、Loaded行、message、終了結果を分けて記録します。

3. active状態とenabled状態を分けて確認する

system unit:

systemctl is-active example.service
systemctl is-enabled example.service

user unit:

systemctl --user is-active example.service
systemctl --user is-enabled example.service

is-active は現在のunit状態を、is-enabledはunit fileの有効化状態を確認します。enabledまたはdisabledはboot時などの起動関係を示す情報で、activeまたはinactiveとは別の概念です。enabledでも現在activeとは限らず、activeでもenabledとは限りません。

activeはsystemd上のunit状態であり、application-levelのhealth、requestへの正常応答、依存先との通信成功まで証明しません。serviceがactiveでも症状が続く場合は、applicationのhealth指標とlogを照合します。

4. 状態と終了結果のpropertyを確認する

system unit:

systemctl show example.service \
  -p LoadState \
  -p ActiveState \
  -p SubState \
  -p Result \
  -p ExecMainCode \
  -p ExecMainStatus

user unit:

systemctl --user show example.service \
  -p LoadState \
  -p ActiveState \
  -p SubState \
  -p Result \
  -p ExecMainCode \
  -p ExecMainStatus

systemctl showはmachine-readableなpropertyを表示します。ActiveStateは高水準の状態、SubStateはunit type固有の詳細状態です。Result、ExecMainCode、ExecMainStatusは直近のservice実行結果とmain processの終了情報を確認する材料ですが、数値や値だけでroot causeを決めません。設定、同時刻のjournal、applicationの仕様と組み合わせます。

propertyの有無や取り得る値はsystemdのversion、unit type、実行履歴によって異なる場合があります。空の値や想定外の値を推測で補わず、導入環境のmanualと表示結果をそのまま記録します。

5. unit fragmentとdrop-inを確認する

system unit:

systemctl cat example.service

user unit:

systemctl --user cat example.service

systemctl catはunitのfragmentとdrop-inのsource fileを表示します。複数のdrop-inがある場合はfile名と設定値を対応させ、想定する設定がどこから来たかを確認します。disk上の内容とsystemd managerが現在認識している内容は、unit fileの変更時点によって一致しない場合があります。

generated unitやtransient unitは、通常の永続的なunit fileと生成元や保管形態が異なる場合があります。通常の配置だけを前提にせず、unitのLoadStateとfragmentの表示を確認します。

unit内容にはEnvironment、command argument、path、hostname、user名、credentialの参照先などの機密情報が含まれる場合があります。共有前に必ずマスクし、unit内容そのものを変更しません。

6. current bootのjournalを対象unitで絞る

system unit:

journalctl -u example.service -b --no-pager -n 100

user unit:

journalctl --user-unit=example.service -b --no-pager -n 100

system unitは-u、user unitは--user-unit=で対応するunitのmessageへ絞ります。-b でcurrent boot、-n 100で直近100件に限定します。systemctl statusに表示された一部logだけで全履歴と断定せず、発生時刻、終了結果、直前変更と時系列で照合します。

journalの保存方式、rotation、保持期間、権限によって、必要な履歴が保存されていない、または呼び出したuserから見えない場合があります。出力がないことだけでeventがなかったとは断定しません。-bはcurrent bootに限定するため、以前のbootはこの結果に含まれません。

終了結果とlogを組み合わせて判断する

failedはsystemdが失敗状態を記録したことを示す材料ですが、それだけでroot causeが確定したわけではありません。ExecMainStatusだけで原因を決めず、Result、SubState、unit設定、journalの同時刻message、application固有の終了statusの意味を照合します。

service状態が正常でも接続できない場合

serviceがactiveで、別の確認で想定portのlisteningも確認できたのに外部から接続できない場合は、Linuxのネットワーク疎通・DNS・待受ポートを切り分ける手順でaddress、route、名前解決、接続経路を分けて確認します。activeやlisteningだけで外部到達性を断定しません。

共有前に出力の機密情報をマスクする

status、unit、journalの出力にはcommand argument、内部path、hostname、user名、environment値、IP address、log本文が含まれる場合があります。元の記録を保持し、共有用コピーでは組織の規程に従って認証情報、個人情報、内部構成を示す値をマスクしてください。

原因確認と復旧操作を分離する

このガイドは状態、設定、終了結果、logを観測して原因候補を絞るところまでです。service状態やunit設定を変える操作、journalの削除、processやhostへの操作には進みません。影響範囲、承認手順、復旧計画を確認し、権限を持つ管理者が別途判断します。

command仕様の参照先

optionやpropertyは導入環境のman pageを優先し、以下のsystemd upstream一次情報も参照してください。

関連ガイド・商品