Evilham
c5929f397d
there are several typos, some style issues and now there is at most one service restart in all cases. Submitted by: pedro <git2021@cas.cat>
171 lines
5.1 KiB
ReStructuredText
171 lines
5.1 KiB
ReStructuredText
cdist-type__evilham_single_binary_service(7)
|
|
============================================
|
|
|
|
NAME
|
|
----
|
|
cdist-type__evilham_single_binary_service - Setup a single-binary service
|
|
|
|
|
|
DESCRIPTION
|
|
-----------
|
|
This type is designed to easily deploy and configure a single-binary service
|
|
named `${__object_id}`.
|
|
|
|
A good example of this are Prometheus exporters.
|
|
|
|
This type makes certain assumptions that might not be correct on your system.
|
|
If you need more flexibility, please get in touch and provide a use-case
|
|
(and hopefully a backwards-compatible patch).
|
|
|
|
This type will place the downloaded binary and, if requested, other extra
|
|
binaries in `/usr/local/bin`.
|
|
|
|
If a `--config-file-source` is provided, it will be placed under:
|
|
`/etc/${__object_id}.conf`.
|
|
|
|
TODO (patches welcome!):
|
|
- It currently only supports `.tar.gz` archives.
|
|
- It currently only supports systemd units.
|
|
- Does not handle properly BSD-systems (wheel group, /usr/local/etc, systemd)
|
|
|
|
|
|
REQUIRED PARAMETERS
|
|
-------------------
|
|
checksum
|
|
This will be passed verbatim to `__download(7)`.
|
|
Use something like `sha256:...`.
|
|
|
|
url
|
|
This will be passed verbatim to `__download(7)`.
|
|
|
|
version
|
|
This type will use a thumbstone file with a "version" number to track
|
|
whether or not a service must be updated.
|
|
This thumbstone file is placed under
|
|
`/usr/local/bin/.${__object_id}.cdist.version`.
|
|
|
|
|
|
BOOLEAN PARAMETERS
|
|
------------------
|
|
unpack
|
|
If present, the contents of `--url` will be treated as an archive to be
|
|
unpacked with `__unpack(7)`.
|
|
See also `--unpack-args` and `--extra-binary`.
|
|
|
|
do-not-manage-user
|
|
Always considered present when `--user` is `root`.
|
|
If present, the user in `--user` will not be managed by this type with
|
|
`__user`, this means it *must* exist beforehand when installing the service
|
|
and it will not be removed by this type.
|
|
|
|
|
|
OPTIONAL PARAMETERS
|
|
-------------------
|
|
config-file-source
|
|
If present, this file's contents will be placed under
|
|
`/etc/${__object_id}.conf` with permissions `0440` and ownership assigned to
|
|
`--user` and `--group`.
|
|
If `-` is passed, this type's `stdin` will be used.
|
|
|
|
user
|
|
The user under which the service will run. Defaults to `root`.
|
|
If this user is not `root` and `--do-not-manage-user` is not present,
|
|
this user will be created or removed as per the `--state` parameter.
|
|
|
|
group
|
|
The group under which the service will run. Defaults to `--user`.
|
|
|
|
state
|
|
Whether the service is to be `present` (default) or `absent`.
|
|
When `absent`, this type will clean any binaries listed in `--extra-binary`
|
|
and also the config file as described in `--config-file-source`.
|
|
|
|
binary
|
|
This will be the binary name. Defaults to `${__object_id}`.
|
|
If `--unpack` is used, a binary with this name must be unpacked.
|
|
Otherwise, the contents of `--url` will be placed under this binary name.
|
|
|
|
service-args
|
|
Any extra arguments to pass along with `--service-exec`. Beware that any
|
|
service-args having the format `--config=/etc/foo.cfg` should be
|
|
represented in the following way `--service-exec='--config=/etc/foo.cfg'`
|
|
|
|
service-exec
|
|
The executable to use for this service.
|
|
Defaults to `/usr/local/bin/BINARY_NAME` where `BINARY_NAME` is the
|
|
resulting value of `--binary`.
|
|
|
|
service-description
|
|
The service description to be used in, e.g. the systemd unit file.
|
|
Defaults to `cdist-managed '${__object_id}' service`.
|
|
|
|
unpack-args
|
|
Only has an effect if `--unpack` is used.
|
|
These arguments will be passed verbatim to `__unpack(7)`.
|
|
Very useful as this type assumes the archive does not have the binaries in
|
|
subdirectories; that can be worked around with
|
|
`--unpack-args '--tar-strip 1'`.
|
|
|
|
|
|
OPTIONAL MULTIPLE PARAMETERS
|
|
----------------------------
|
|
extra-binary
|
|
Only useful with `--unpack`.
|
|
If passed, these binaries will also be installed when `--state` is `present`
|
|
and removed when `--state` is `absent`.
|
|
Handle with care :-).
|
|
|
|
|
|
EXAMPLES
|
|
--------
|
|
|
|
.. code-block:: sh
|
|
|
|
# Install and enable the ipmi_exporter service
|
|
# The variables are defined in the manifest previously
|
|
__evilham_single_binary_service ipmi_exporter \
|
|
--user "${USER}" \
|
|
--service-args ' --config.file=/etc/ipmi_exporter.conf' \
|
|
--version "${SHOULD_VERSION}" \
|
|
--checksum "${CHECKSUM}" \
|
|
--url "${DOWNLOAD_URL}" \
|
|
--state "present" \
|
|
--unpack \
|
|
--unpack-args "--tar-strip 1" \
|
|
--config-file-source '-' <<-EOF
|
|
# Remotely managed, changes will be lost
|
|
# [...] config contents goes here
|
|
EOF
|
|
|
|
# Remove the ipmi_exporter service along with the user and its config
|
|
__evilham_single_binary_service ipmi_exporter \
|
|
--user "${USER}" \
|
|
--version "${SHOULD_VERSION}" \
|
|
--checksum "${CHECKSUM}" \
|
|
--url "${DOWNLOAD_URL}" \
|
|
--state "absent"
|
|
|
|
# Same, but the service was using my user! Let's not delete that!
|
|
__evilham_single_binary_service ipmi_exporter \
|
|
--user "evilham" \
|
|
--do-not-manage-user \
|
|
--version "${SHOULD_VERSION}" \
|
|
--checksum "${CHECKSUM}" \
|
|
--url "${DOWNLOAD_URL}" \
|
|
--state "absent"
|
|
|
|
|
|
SEE ALSO
|
|
--------
|
|
- `__download(7)`
|
|
- `__unpack(7)`
|
|
|
|
|
|
AUTHORS
|
|
-------
|
|
Evilham <contact@evilham.com>
|
|
|
|
|
|
COPYING
|
|
-------
|
|
Copyright \(C) 2021 Evilham.
|