cimon-io.systemd-service

Ansible systemd サービスロール

Ansible ロールは systemd サービスユニット ファイルを作成し、設定します。これにより、特定のサービスを自動的にバックグラウンドで実行したり、特定のイベントのために有効または無効にしたり、プロセスのグループを管理したり、他のユニットへの依存関係を設定したりできます。

このロールには次のタスクが含まれています：

/etc/systemd/system/ に、指定された名前 service_name.service の systemd サービスファイルを作成する。
重要なユニット、サービス、インストールセクションのオプションを設定する。
systemd に新しいサービスファイルが存在することを通知し、サービスを再起動する。
必要に応じて、サービスの自動起動を有効にする。

要件

このロールには root アクセスが必要です。プレイブックで become: yes パラメータを使用して実行するか、次のようにロールを呼び出してください：

- hosts: apps
  roles:
    - role: systemd_service
      become: yes

ロール変数

必要なサービスは systemd_service 辞書変数で指定できます（defaults/main.yml を参照）。

systemd_service: {}

各サービスには service_name と必要なパラメータ値を設定してください。たとえば、サービスが起動時に開始されるかどうかを指定するには enabled パラメータを使用します。

systemd_service:
  service:
    service_name:
    enabled:

service_name キー（ネストしたパラメータの形）のために指定すべき他の利用可能なパラメータは以下の通りです。

ユニットセクションのオプション

このパラメータグループはユニットに関する一般的な情報を含みます。

description:   # ユニットを説明する自由形式の文字列

次の2つのパラメータは他のユニットへの依存関係を設定します。サービスがアクティブになると、ここにリストされたユニットもアクティブになります。もし requires ユニットの1つが実行できない、または突然失敗した場合、そのサービスも停止します。一方、 wants リストでは、リストのユニットが非アクティブになってもサービスは停止しません。パラメータにはスペースで区切ったユニット名を複数指定できます。

requires:   # サービスと一緒に起動しなければならないユニット
wants:      # サービスと一緒に起動するべきユニット

サービスの起動または停止の順序を設定するには、次のパラメータを使用します。ユニット間に順序依存関係がない場合は、同時にシャットダウンまたは起動されます。どちらのパラメータもスペースで区切ったユニットのリストで設定されます。

after:   # サービスの後に起動しなければならないユニット
before:  # サービスの前に起動しなければならないユニット

サービスセクションのオプション

このセクションにはサービスとその監視プロセスに関する情報が含まれます。 type パラメータはこのサービスユニットのプロセス起動タイプを設定します。

type:

使用できる値は以下の通りです：

simple - このタイプはサービスが即座に起動されることを想定しています。プロセスは分岐しない必要があります。サービスが他のサービスに依存関係を持っている場合は、このタイプを使用しないでください。サービスがシステム上の他のプロセスに機能を提供する場合、その通信チャネルはデーモンが起動される前に設定する必要があります。
forking - サービスは一度起動され、親プロセスの完了とともにプロセスが分岐します。このタイプはクラシックなデーモンを起動するために使用されます。このモードを使用する場合、systemd がデーモンのメインプロセスを識別できるように pid_file パラメータを使用することを推奨します。

他の値の動作は simple と似ています。しかし、一部の違いがあります：

oneshot - サービスは systemd が次のユニットを起動する前に終了することが期待されます；
dbus - デーモンが D-Bus バス上で名前を取得することが期待されます；
notify - デーモンは起動が完了したときに sd_notify(3) を介して通知メッセージを送信します；
idle - サービスバイナリの実行は、すべてのアクティブなジョブが処理されるまで遅延されます。このタイプはコンソール出力を改善するために便利ですが、一般のユニットの順序制御ツールとしては便利ではありません。

forking 起動タイプを使用するには、PIDファイルのパスを設定します。

pid_file:    # このデーモンのPIDファイルを指す絶対ファイル名

サービスを実行する UNIX ユーザーとグループを指定できます。パラメータは単一のユーザーまたはグループ名、または数値 ID を値として取ります。システムサービスおよび root ユーザーのユーザーサービスのデフォルトは root ですが、他のものに変更できます。他のユーザーのユーザーサービスでは、ユーザーIDの切り替えは許可されていません。したがって、許可されている唯一の値は、そのユーザーのサービスマネージャが実行されているユーザーと同じユーザーです。グループが設定されていない場合はデフォルトのユーザーグループが使用されます。

user:
group:

次のパラメータでユニットのスケジューリング優先度を設定します。これは -20（最高の優先度）から 19（最低の優先度）までの整数を取ります。

nice:    # サービスのデフォルトナイスレベル

Out-Of-Memoryキラーのプロセスに対する調整レベルは次のオプションで指定されます。これは -1000（OOM キリングを無効にする）から 1000（OOM キリングが好ましい）までの整数値を取ります。

oom_score_adjust:

次のパラメータでは、サービスの状態に応じて実行されるコマンドを指定できます。パラメータは複数回使用できるか、いくつかのコマンドを含めることができます。複数のコマンド行は、セミコロンで区切って単一の指示に連結できます。実行するコマンドは絶対パス名で指定する必要があります。スペースを含む場合は、割り当てに二重引用符を使用してください。各コマンドの最初の引数は実行可能ファイルへの絶対パスでなければなりません。空の文字列は、そのパラメータの前に指定されたコマンドのリストをリセットします。

# このサービスが起動するときに実行されるコマンド
# `type` が `oneshot` でない限り、ここに正確に1つのコマンドを指定する必要があります
exec_start:

# `exec_start` コマンドの前に実行されるコマンド
exec_start_pre:

# `exec_start` コマンドの後に実行されるコマンド
exec_start_post:

# `exec_start` で開始されたサービスを停止するために実行されるコマンド
exec_stop:

# サービスが停止した後に実行されるコマンド
exec_stop_post:

# サービス内で設定の再読み込みをトリガーするために実行されるコマンド
exec_reload:

サービスプロセス（主要なサービスプロセスまたは 'exec_start_pre'、'exec_start_post'、'exec_stop'、'exec_stop_post'、または 'exec_reload' パラメータで指定されたもの）の終了、強制終了、またはタイムアウトが発生したときにサービスを再起動するかどうかを設定します。 restart パラメータは次のいずれかの値を取ります：

no （デフォルト） - サービスは再起動されません；
on-success - サービスプロセスが正常に終了したとき（終了コードが 0 の場合、または SIGHUP、SIGINT、SIGTERM、SIGPIPE のいずれかの信号）にのみ再起動されます；
on-failure - プロセスが非ゼロの終了コードで終了した場合、信号によって終了された場合、操作がタイムアウトした場合、設定されたウォッチドッグのタイムアウトが発生した場合にサービスは再起動されます；
on-abnormal - プロセスが信号によって強制終了された場合、操作がタイムアウトした場合、またはウォッチドッグタイムアウトが発生した場合にサービスは再起動されます；
on-watchdog - サービスプロセスがクリーン終了ステータスとして指定されていない信号によって終了した場合にのみ、サービスは再起動されます；
on-abort - サービスのウォッチドッグタイムアウトが発生した場合にのみサービスが再起動されます；
always - サービスは常に再起動されます。

# サービスを再起動しなければならないとき
restart:

上記のコマンドの遅延時間を次のパラメータで指定できます。これらは秒数または '5min 20s' のような時間のスパン値を取ります。 restart_sec パラメータは、サービスを再起動する前にスリープする時間を設定します（restart で設定）。 timeout_sec オプションは、起動/停止コマンドの処理のために待機する時間を定義します。

restart_sec:
timeout_sec:

environment パラメータを使用して実行されるプロセスの環境変数リストを設定します。これには変数とその値の辞書が含まれます。値にスペースが含まれている場合は、割り当てに二重引用符を使用します。

環境変数をテキストファイルから読み取ることもできます。このためには、 environment_file パラメータの値をファイルパスに設定します。

environment:       # 環境変数の辞書
environment_file:  # 環境変数が含まれるファイルのパス

作業ディレクトリは次のパラメータで指定します。起動コマンドを実行する前に、現在のディレクトリとして設定されます。

working_directory:

次のパラメータでは、実行されるプロセスのファイルディスクリプタ（STDIN、STDOUT、STDERR）を接続する場所を選択できます。 standard_input パラメータは "null"、"tty"、"tty-force"、"tty-fail"、"socket" または "fd" の値を取ります。standard_output パラメータは "inherit"、"null"、"tty"、"journal"、"syslog"、"kmsg"、"journal+console"、"syslog+console"、"kmsg+console"、"socket" または "fd" と等しくなります。 standard_error の利用可能な値は standard_output と同じです。

standard_input:
standard_output:
standard_error:

"standard_*" パラメータのいずれかに "tty"、"tty-force"、または "tty-fail" が指定されている場合、tty のパスを指定できます。

tty_path:

サービスが作成または変更された後に再起動／再読み込み／起動／停止の状態になる必要があるかどうかを設定します。

state:

次の値を取ることができます： restarted（デフォルト） reloaded started stopped

インストールセクションのオプション

このセクションの変数は、ユニットのインストール情報を保持します。次の2つのパラメータは複数回使用することができ、ユニット名のスペース区切りリストを指定できます。リストには、requires と wants フィールドからこのサービスを参照するユニットが含まれます。

wanted_by:
required_by:

依存関係

なし

例プレイブック

- hosts: app
  roles:
    - role: systemd_service
       systemd_service:
        # デフォルトのサービス名
        railsapp:
          # サービス名
          service_name: railsapp
          # 起動時にサービスを開始
          enabled: Yes
          # サービスが起動するときに指定された引数でコマンドを実行
          exec_start: "/bin/bash -lc 'puma -C config/puma.rb'"
          # 指定したディレクトリをカレントとして使用
          working_directory: "/var/www/myapp"
          # 環境変数を指定
          environment: {ENVVAR: value}
          # ユーザーとグループの下でプロセスを実行
          user: "deploy"
          group: "deploy"
          # クリーンな終了コードまたは信号が得られない場合にのみサービスを再起動
          restart: "on-failure"
          # 可能であれば 'redis' をアクティブにする
          wants: "redis.service"
          # 'postgresql' を起動するか、失敗した場合には動作を停止
          requires: "postgresql.service"
          # multi-user.target ユニットがサービスを実行することを好む
          wanted_by: "multi-user.target"