cdist-contrib/type/__single_binary_service/man.rst

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`.

This type supports services managed by `__runit(7)` when `systemd` is not
the init system being used.


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.

user-home-dir
    Does not have an effect if `--do-not-manage-user` is used or `--user` is
    `root`.
    The home directory of the service user. It will be created.
    Defaults to `/nonexistent`, in this case the home directory will not be
    created.

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-definition
    The service definition to be used as an override.
    Note that this type decides dinammically between runit and systemd, and
    you can currently only define either a systemd unit or a runit script here.
    Use this parameter only for testing and get in touch to discuss how your
    particular use-case can be supported by the type.

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'`.

unpack-extension
    Only has an effect if `--unpack` is used.
    The file extension of the file to unpack, defaults to `.tar.gz`.

working-directory
    If set, the working directory with which the service will be started.


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.