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

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

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

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

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

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

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

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は索引ページに相当し、 全ての設定項目名と、それが記載されているページが一覧になっています。

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

（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のページの当該項目に説明があります。

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を開いてその設定項目名で検索します。 該当ページが分かれば、そこから詳細な仕様を確認できます。

• https://www.man7.org/linux/man-pages/ : 正確性や公式性が高く評価されているらしい
• https://ja.manpages.org/ : 日本語を含む複数言語に強い
• https://man.archlinux.org/ : 日々更新が行われるため最新の情報に強いArch Linuxのmanページ。デザインもモダンでスマホなどでも読みやすそう。

RailsでMailクラスに遭遇したら、それはmail gemのものです。ですので、そのAPI情報などは、Railsの情報源ではなく、以下のようなmail gemの情報源を見ると得られます。

• GitHub: https://github.com/mikel/mail
• APIドキュメント: https://www.rubydoc.info/gems/mail/

要点

Active Recordのマイグレーションファイルにてt.referencesまたはadd_referenceを使う際、 foreign_key:オプションに対してtrueの代わりに ハッシュを渡すことで外部キー制約の詳細を設定 できます。

このハッシュで指定できるオプションはadd_foreign_keyのAPIドキュメントに記載されているオプションです。

具体例

t.references を使う場合（新規テーブル作成時）

create_table :books do |t|
  t.references :author, foreign_key: { on_delete: :cascade }
end

add_reference を使う場合（既存テーブルへの追加）

add_reference :books, :author, foreign_key: { on_delete: :cascade }

説明

Active Recordのマイグレーションファイルにてテーブル間に関連付けをする際には、 t.referencesまたはadd_referenceを使うと便利です。

この2つのメソッドは、呼び出すときにforeign_key:オプションを付けると、 外部キー制約も同時に付与することが出来ます。例えば、foreign_key: trueという記述をよく見かけます。

foreign_key: trueは外部キー制約をかけることだけの指定となりますが、 ここでのtrueの代わりにハッシュを渡すことで、外部キー制約の詳細が設定可能になります。

このハッシュの中に入れられるオプション、つまり外部キー制約の詳細設定項目は、add_foreign_keyに渡せるオプションと同じです。 このadd_foreign_keyに渡せるオプションの具体的な種類とそれぞれの意味については、 add_foreign_keyのAPIドキュメントをご覧ください。

Railsガイドを一読しただけでは、 add_foreign_keyとadd_referenceが、それぞれどのようなもので、どう違うのかがいまいちよく分かりませんでした。 そこで、add_foreign_keyとadd_referenceによってdb/schema.rbがどのように変化するかを基に、 それぞれの機能について確認してみました。

add_foreign_key

add_foreign_keyは外部キー制約の追加だけを行います。よって、カラムやインデックスの追加は行いません。

外部キー制約とは、子テーブルが参照している親のIDが親テーブルに存在することをデータベースレベルで保証する制約です。

例えば、以下の記述をマイグレーションファイルに行ったとします。

add_foreign_key :products, :users

すると以下の記述がdb/schema.rbに追加されます。

add_foreign_key "products", "users"

この記述は、products（子テーブル）のuser_idカラムに登場するIDが、users（親テーブル）のidカラムに必ず存在するように制約をかけています。

add_reference

add_referenceは、テーブル間の関連付けに関する複数の設定を一度に行える便利メソッドです。

add_referenceの基本機能は、カラムとインデックスの追加です。 例えば、以下の記述をマイグレーションファイルに行ったとします。

add_reference :products, :user

すると以下のように、users（親テーブル）に関連付ける2つの記述、具体的にはuser_idのカラムとインデックスをproducts（子テーブル）に追加する2つの記述が、db/schema.rbに追加されます。

t.integer "user_id"
t.index ["user_id"], name: "index_products_on_user_id"

またadd_referenceは、foreign_key:trueオプションを追加することで、前述の2つに加えて外部キー制約も同時に設定できます。 例えば、以下の記述をマイグレーションファイルに行ったとします。

add_reference :products, :user, foreign_key:true

すると以下のように、前述の2つの記述に加えて、add_foreign_keyの記述がdb/schema.rbに追加されます。

t.integer "user_id"
t.index ["user_id"], name: "index_products_on_user_id"
add_foreign_key "products", "users"

（参考）add_referenceとt.referencesの機能は基本的に同じ

add_referenceとcreate_tableのブロックの中で呼び出すt.referencesは基本的に同じ機能を提供します（オプション以外の引数の部分で違いはありますが。） 実際にt.referencesへ渡せるオプションはadd_referenceと同じです。 また、t.referencesの実装とadd_referenceの実装のどちらもReferenceDefinition.newを内部で呼ぶ形になっています（v8.1.2で確認）。

Active RecordのTransactionブロック内で例外が投げられた場合、ActiveRecord::Rollback以外の例外はロールバックの後に再度投げられます。

したがって、処理失敗で例外を投げるメソッド（save!等）を使えば、基本的にその例外はロールバックの後Transactionブロックの外へ伝播します。 これをキャッチしなければ、RailsはHTTPのエラーレスポンスをブラウザ等のクライアントに返します。 つまり、「処理に失敗したら、ロールバックして、あとの処理は切り上げて、エラーレスポンスを返す」という挙動は簡単に実装できます。

一方で、「ロールバック後に例外を出さずに処理を継続する」場合には、ActiveRecord::Rollbackを活用できます。 以下は、Transactionの成否でリダイレクト先を変えるコード例です。

completed = false

ActiveRecord::Base.transaction do
  unless obj1.save && obj2.save
    raise ActiveRecord::Rollback
  end
  completed = true
end

if completed
  redirect_to completed_path
else
  redirect_to uncompleted_path
end

RubyのHash#mergeのマニュアルでは、 その引数はハッシュとしか書かれていません。 例えば、以下のような形です。

irb(main):001> {f1: 1, f2: 2}.merge({b3: 3})
=> {:f1=>1, :f2=>2, :b3=>3}

では、キーワード引数を渡すとどうなるのかと言うと、以下のように動きはしますよ、という小ネタです。

irb(main):002> {f1: 1, f2: 2}.merge(b3: 3)
=> {:f1=>1, :f2=>2, :b3=>3}

Rubyの言語仕様上OKなのかは不明ですので、自分から積極的に使うというよりは、 他人のコードを読むときに役立つかもしれない小ネタ知識でした。

1/9にリリースされたRails v8.1.2は、minitest6で問題なさそうです。簡単にテストした分には、正常にテストが走りました。

ちなみにv8.1.1は、minitest6にすると、エラーにはならないものの、テストが全く拾われず0 runs, 0 assertions, 0 failures, 0 errors, 0 skipsになっていました。

WSLでUbuntu 24.04の利用を始めてから、 一部のGUIアプリ（meldなど）の起動に異常に時間がかかる問題にずっと悩まされていました。 本日以下のようにコマンドプロンプトでwsl --updateを実行して、この問題がやっと解決しました。

なお、この問題に対する修正は WSL2.5.1で導入されたそうです。

C:\Users\wakai>wsl.exe -v
WSL バージョン: 2.4.11.0
カーネル バージョン: 5.15.167.4-1
WSLg バージョン: 1.0.65
MSRDC バージョン: 1.2.5716
Direct3D バージョン: 1.611.1-81528511
DXCore バージョン: 10.0.26100.1-240331-1435.ge-release
Windows バージョン: 10.0.26200.7462

C:\Users\wakai>wsl --update
更新プログラムを確認しています。
Linux 用 Windows サブシステムをバージョンに更新しています: 2.6.3。

C:\Users\wakai>wsl.exe -v
WSL バージョン: 2.6.3.0
カーネル バージョン: 6.6.87.2-1
WSLg バージョン: 1.0.71
MSRDC バージョン: 1.2.6353
Direct3D バージョン: 1.611.1-81528511
DXCore バージョン: 10.0.26100.1-240331-1435.ge-release
Windows バージョン: 10.0.26200.7462

参考情報

• https://github.com/microsoft/wslg/issues/1250
• https://learn.microsoft.com/ja-jp/windows/wsl/basic-commands

基本はダブルクォーテーション付きの"$@"

シェルスクリプトに渡された全ての引数を、そのシェルスクリプト内で別のコマンドに引き渡す場合は"$@"を使います。 例えば、以下のように記述します。

grep -n cat "$@" | sed "s/cat/__CAT__/g" | tee -a ~/foo.log

"$*"や$@（ダブルクォーテーションなし）を使うと、'foo bar'のようなスペースを含む引数がスペースで分割されて壊れてしまいます。

shコマンドに渡すときはsh -c '..."$@"...' -- "$@"

1つの実行コマンドしか受け付けないsudoやssh、docker runなどで、 複数コマンドの実行などの複雑な処理を行いたいときに活躍するのがsh -c '...'です。

シェルスクリプト内でsh -c '...'にすべての引数を渡したいときは、sh -c '..."$@"...' -- "$@"と記述します。 例えば、以下のように記述します。

sudo sh -c 'grep -n cat "$@" | sed "s/cat/__CAT__/g" | tee -a /var/log/foo.log' -- "$@"

先頭のいくつかの引数を取り出して残りを渡す場合（おまけ）

検索ワードのような「固定の引数」と、複数のファイルのような「可変長の引数」が混在しているケースです。 これらをまとめてsudoやssh、docker runなどに投げたい場合は、 -cオプションの文字列内でshiftを使います。

以下は、第一引数が検索文字列、第二引数がその検索文字列を置き換える先の文字列、 第三引数以降はこの検索と置換の対象となるファイル（複数個指定可）となっている例です。

sudo sh -c 'pattern="$1"; replace="$2"; shift 2;
            grep -n "$pattern" "$@" |
            sed "s/$pattern/$replace/g" |
            tee -a /var/log/foo.log' -- "$@"