3rdparty/modules/systemd/README.md

   1 # Systemd
   2
   3 [![Puppet Forge](http://img.shields.io/puppetforge/v/camptocamp/systemd.svg)](https://forge.puppetlabs.com/camptocamp/systemd)
   4 [![Build Status](https://travis-ci.org/camptocamp/puppet-systemd.png?branch=master)](https://travis-ci.org/camptocamp/puppet-systemd)
   5
   6 ## Overview
   7
   8 This module declares exec resources to create global sync points for reloading systemd.
   9
  10 **Version 2 and newer of the module don't work with Hiera 3! You need to migrate your existing Hiera setup to Hiera 5**
  11
  12 ## Usage and examples
  13
  14 There are two ways to use this module.
  15
  16 ### unit files
  17
  18 Let this module handle file creation and systemd reloading.
  19
  20 ```puppet
  21 systemd::unit_file { 'foo.service':
  22  source => "puppet:///modules/${module_name}/foo.service",
  23 }
  24 ~> service {'foo':
  25   ensure => 'running',
  26 }
  27 ```
  28
  29 Or handle file creation yourself and trigger systemd.
  30
  31 ```puppet
  32 include systemd::systemctl::daemon_reload
  33
  34 file { '/usr/lib/systemd/system/foo.service':
  35   ensure => file,
  36   owner  => 'root',
  37   group  => 'root',
  38   mode   => '0644',
  39   source => "puppet:///modules/${module_name}/foo.service",
  40 }
  41 ~> Class['systemd::systemctl::daemon_reload']
  42
  43 service {'foo':
  44   ensure    => 'running',
  45   subscribe => File['/usr/lib/systemd/system/foo.service'],
  46 }
  47 ```
  48
  49 You can also use this module to more fully manage the new unit. This example deploys the unit, reloads systemd and then enables and starts it.
  50
  51 ```puppet
  52 systemd::unit_file { 'foo.service':
  53  source => "puppet:///modules/${module_name}/foo.service",
  54  enable => true,
  55  active => true,
  56 }
  57 ```
  58
  59 ### drop-in files
  60
  61 Drop-in files are used to add or alter settings of a unit without modifying the
  62 unit itself. As for the unit files, the module can handle the file and
  63 directory creation and systemd reloading:
  64
  65 ```puppet
  66 systemd::dropin_file { 'foo.conf':
  67   unit   => 'foo.service',
  68   source => "puppet:///modules/${module_name}/foo.conf",
  69 }
  70 ~> service {'foo':
  71   ensure    => 'running',
  72 }
  73 ```
  74
  75 Or handle file and directory creation yourself and trigger systemd:
  76
  77 ```puppet
  78 include systemd::systemctl::daemon_reload
  79
  80 file { '/etc/systemd/system/foo.service.d':
  81   ensure => directory,
  82   owner  => 'root',
  83   group  => 'root',
  84 }
  85
  86 file { '/etc/systemd/system/foo.service.d/foo.conf':
  87   ensure => file,
  88   owner  => 'root',
  89   group  => 'root',
  90   mode   => '0644',
  91   source => "puppet:///modules/${module_name}/foo.conf",
  92 }
  93 ~> Class['systemd::systemctl::daemon_reload']
  94
  95 service {'foo':
  96   ensure    => 'running',
  97   subscribe => File['/etc/systemd/system/foo.service.d/foo.conf'],
  98 }
  99 ```
 100
 101 ### tmpfiles
 102
 103 Let this module handle file creation and systemd reloading
 104
 105 ```puppet
 106 systemd::tmpfile { 'foo.conf':
 107   source => "puppet:///modules/${module_name}/foo.conf",
 108 }
 109 ```
 110
 111 Or handle file creation yourself and trigger systemd.
 112
 113 ```puppet
 114 include systemd::tmpfiles
 115
 116 file { '/etc/tmpfiles.d/foo.conf':
 117   ensure => file,
 118   owner  => 'root',
 119   group  => 'root',
 120   mode   => '0644',
 121   source => "puppet:///modules/${module_name}/foo.conf",
 122 }
 123 ~> Class['systemd::tmpfiles']
 124 ```
 125
 126 ### service limits
 127
 128 Manage soft and hard limits on various resources for executed processes.
 129
 130 ```puppet
 131 systemd::service_limits { 'foo.service':
 132   limits => {
 133     'LimitNOFILE' => 8192,
 134     'LimitNPROC'  => 16384,
 135   }
 136 }
 137 ```
 138
 139 Or provide the configuration file yourself. Systemd reloading and restarting of the service are handled by the module.
 140
 141 ```puppet
 142 systemd::service_limits { 'foo.service':
 143   source => "puppet:///modules/${module_name}/foo.conf",
 144 }
 145 ```
 146
 147 ### network
 148
 149 systemd-networkd is able to manage your network configuration. We provide a
 150 defined resource which can write the interface configurations. systemd-networkd
 151 needs to be restarted to apply the configs. The defined resource can do this
 152 for you:
 153
 154 ```puppet
 155 systemd::network{'eth0.network':
 156   source          => "puppet:///modules/${module_name}/eth0.network",
 157   restart_service => true,
 158 }
 159 ```
 160
 161 ### Services
 162
 163 Systemd provides multiple services. Currently you can manage `systemd-resolved`,
 164 `systemd-timesyncd` and `systemd-networkd` via the main class:
 165
 166 ```puppet
 167 class{'systemd':
 168   manage_resolved  => true,
 169   manage_networkd  => true,
 170   manage_timesyncd => true,
 171 }
 172 ```
 173
 174 $manage_networkd is required if you want to reload it for new
 175 `systemd::network` resources. Setting $manage_resolved will also manage your
 176 `/etc/resolv.conf`.
 177
 178 When configuring `systemd::resolved` you could set `dns_stub_resolver` to false (default) to use a *standard* `/etc/resolved.conf`, or you could set it to `true` to use the local resolver provided by `systemd-resolved`.
 179
 180 It is possible to configure the default ntp servers in /etc/systemd/timesyncd.conf:
 181
 182 ```puppet
 183 class{'systemd':
 184   manage_timesyncd    => true,
 185   ntp_server          => ['0.pool.ntp.org', '1.pool.ntp.org'],
 186   fallback_ntp_server => ['2.pool.ntp.org', '3.pool.ntp.org'],
 187 }
 188 ```
 189
 190 This requires puppetlabs-inifile, which is only a soft dependency in this module (you need to explicitly install it). Both parameters accept a string or an array.
 191
 192 ### Resource Accounting
 193
 194 Systemd has support for different accounting option. It can track
 195 CPU/Memory/Network stats per process. This is explained in depth at [systemd-system.conf](https://www.freedesktop.org/software/systemd/man/systemd-system.conf.html).
 196 This defaults to off (default on most operating systems). You can enable this
 197 with the `$manage_accounting` parameter. The module provides a default set of
 198 working accounting options per operating system, but you can still modify them
 199 with `$accounting`:
 200
 201 ```puppet
 202 class{'systemd':
 203   manage_accounting => true,
 204   accounting        => {
 205     'DefaultCPUAccounting'    => 'yes',
 206     'DefaultMemoryAccounting' => 'no',
 207   }
 208 }
 209 ```