Add documentation for systemd

elastic · Nov 6, 2018 · 8eab223 · 8eab223
1 parent fa771b6
commit 8eab223
Show file tree

Hide file tree

Showing 7 changed files with 123 additions and 0 deletions.
diff --git a/auditbeat/docs/setting-up-running.asciidoc b/auditbeat/docs/setting-up-running.asciidoc
@@ -22,6 +22,8 @@ This section includes additional information on how to set up and run
 
 * <<running-on-kubernetes>>
 
+* <<running-with-systemd>>
+
 
 //MAINTAINERS: If you add a new file to this section, make sure you update the bulleted list ^^ too.
 
@@ -35,4 +37,6 @@ include::./running-on-docker.asciidoc[]
 
 include::./running-on-kubernetes.asciidoc[]
 
+include::../../libbeat/docs/shared-systemd.asciidoc[]
+
 include::../../libbeat/docs/shared-shutdown.asciidoc[]
diff --git a/filebeat/docs/setting-up-running.asciidoc b/filebeat/docs/setting-up-running.asciidoc
@@ -22,6 +22,8 @@ This section includes additional information on how to set up and run
 
 * <<running-on-kubernetes>>
 
+* <<running-with-systemd>>
+
 
 //MAINTAINERS: If you add a new file to this section, make sure you update the bulleted list ^^ too.
 
@@ -35,4 +37,6 @@ include::./running-on-docker.asciidoc[]
 
 include::./running-on-kubernetes.asciidoc[]
 
+include::../../libbeat/docs/shared-systemd.asciidoc[]
+
 include::../../libbeat/docs/shared-shutdown.asciidoc[]
diff --git a/heartbeat/docs/setting-up-running.asciidoc b/heartbeat/docs/setting-up-running.asciidoc
@@ -20,6 +20,8 @@ This section includes additional information on how to set up and run
 
 * <<running-on-docker>>
 
+* <<running-with-systemd>>
+
 //MAINTAINERS: If you add a new file to this section, make sure you update the bulleted list ^^ too.
 
 include::../../libbeat/docs/shared-directory-layout.asciidoc[]
@@ -30,4 +32,6 @@ include::../../libbeat/docs/command-reference.asciidoc[]
 
 include::./running-on-docker.asciidoc[]
 
+include::../../libbeat/docs/shared-systemd.asciidoc[]
+
 include::../../libbeat/docs/shared-shutdown.asciidoc[]
diff --git a/journalbeat/docs/setting-up-running.asciidoc b/journalbeat/docs/setting-up-running.asciidoc
@@ -26,6 +26,8 @@ This section includes additional information on how to set up and run
 
 //* <<running-{beatname_lc}-on-kubernetes>>
 
+* <<running-with-systemd>>
+
 * <<shutdown>>
 
 
@@ -41,4 +43,6 @@ include::../../libbeat/docs/command-reference.asciidoc[]
 
 //include::./running-on-kubernetes.asciidoc[]
 
+include::../../libbeat/docs/shared-systemd.asciidoc[]
+
 include::../../libbeat/docs/shared-shutdown.asciidoc[]
diff --git a/libbeat/docs/shared-systemd.asciidoc b/libbeat/docs/shared-systemd.asciidoc
@@ -0,0 +1,99 @@
+[[running-with-systemd]]
+=== { beatname_uc } and systemd 
+
+DEB and RPM packages include a service unit for Linux systems with systemd. On
+these systems { beatname_uc } can be managed with the usual systemd commands:
+
+==== Starting and stoping { beatname_uc}
+
+When using systemd, { beatname_uc } can be started or stopped with `systemctl`.
+
+["source", "sh", subs="attributes"]
+------------------------------------------------
+systemctl start {beatname_lc}
+------------------------------------------------
+
+["source", "sh", subs="attributes"]
+------------------------------------------------
+systemctl stop {beatname_lc}
+------------------------------------------------
+
+Service start on system boot can be enabled or disabled with `systemctl`,
+{ beatname_uc } is enabled when installed.
+
+["source", "sh", subs="attributes"]
+------------------------------------------------
+systemctl enable {beatname_lc}
+------------------------------------------------
+
+["source", "sh", subs="attributes"]
+------------------------------------------------
+systemctl disable {beatname_lc}
+------------------------------------------------
+
+
+==== { beatname_uc } status and logs
+
+Service status can be also obtained with `systemctl`.
+
+["source", "sh", subs="attributes"]
+------------------------------------------------
+systemctl start {beatname_lc}
+------------------------------------------------
+
+Logs are stored by default in journald, they can be viewed with `journalctl`.
+
+["source", "sh", subs="attributes"]
+------------------------------------------------
+journalctl -u {beatname_lc}.service
+------------------------------------------------
+
+NOTE: Unit file included in packages sets by default `-e` flag, that flag makes
+{ beatname_uc } to log to stderr and disables other log outputs. Systemd stores
+all output sent to stderr in journald.
+
+[float]
+=== Customizing systemd unit for { beatname_uc }
+
+Systemd service unit file includes some environment variables that can be
+overriden to change default options.
+[cols="<h,<,<m,<m",options="header",]
+|=======================================
+| Variable | Description | Default value
+| BEAT_LOG_OPTS | Log options | `-e`
+| BEAT_CONFIG_OPTS | Flags for configuration file path | `-c /etc/{ beatname_lc }/{ beatname_lc }.yml`
+| BEAT_PATH_OPTS | Other paths | -path.home /usr/share/{ beatname_lc } -path.config /etc/{ beatname_lc } -path.data /var/lib/{ beatname_lc } -path.logs /var/log/{ beatname_lc }
+|=======================================
+
+These variables can be overriden with a drop-in unit file placed in `/etc/systemd/system/{ beatname_lc }.service.d` directory.
+
+For example a file with the following content placed in `/etc/systemd/system/{ beatname_lc }.service.d/debug.conf`
+would override `BEAT_LOG_OPTS` to enable debug for Elasticsearch output.
+
+["source", "systemd", subs="attributes"]
+------------------------------------------------
+[Service]
+Environment=BEAT_LOG_OPTS="-e -d elasticsearch"
+------------------------------------------------
+
+It can also be emptied to rely on settings on the configuration file for
+logging.
+
+["source", "systemd", subs="attributes"]
+------------------------------------------------
+[Service]
+Environment=BEAT_LOG_OPTS=""
+------------------------------------------------
+
+Remember to reload systemd configuration and restart the service to apply
+changes on these files.
+
+["source", "sh", subs="attributes"]
+------------------------------------------------
+systemctl daemon-reload
+systemctl restart { beatname_lc }
+------------------------------------------------
+
+NOTE: It is recommended to use some configuration management tool to include
+drop-in unit files, but when needed to add a drop-in by hand `systemctl edit { beatname_lc }.service
+can be used-
diff --git a/metricbeat/docs/setting-up-running.asciidoc b/metricbeat/docs/setting-up-running.asciidoc
@@ -22,6 +22,8 @@ This section includes additional information on how to set up and run
 
 * <<running-on-kubernetes>>
 
+* <<running-with-systemd>>
+
 //MAINTAINERS: If you add a new file to this section, make sure you update the bulleted list ^^ too.
 
 include::../../libbeat/docs/shared-directory-layout.asciidoc[]
@@ -34,4 +36,6 @@ include::./running-on-docker.asciidoc[]
 
 include::./running-on-kubernetes.asciidoc[]
 
+include::../../libbeat/docs/shared-systemd.asciidoc[]
+
 include::../../libbeat/docs/shared-shutdown.asciidoc[]
diff --git a/packetbeat/docs/setting-up-running.asciidoc b/packetbeat/docs/setting-up-running.asciidoc
@@ -20,6 +20,8 @@ This section includes additional information on how to set up and run
 
 * <<running-on-docker>>
 
+* <<running-with-systemd>>
+
 //MAINTAINERS: If you add a new file to this section, make sure you update the bulleted list ^^ too.
 
 include::../../libbeat/docs/shared-directory-layout.asciidoc[]
@@ -30,4 +32,6 @@ include::../../libbeat/docs/command-reference.asciidoc[]
 
 include::./running-on-docker.asciidoc[]
 
+include::../../libbeat/docs/shared-systemd.asciidoc[]
+
 include::../../libbeat/docs/shared-shutdown.asciidoc[]