caretakerd

Version: 0.1.7

caretakerd is build for to be a minimal process supervisor, with no dependencies, optimized for containerization (such as Docker) and simple to configure.

Topics

• Features
• Getting started
• Downloads
• Commands
• Configuration
• Data Types
• Support
• Contributing
• License

Features

• Simple configuration
  Configure everything via one YAML file. Every configuration could also be overwritten via environment variables and the master service could receive its command line also from the command line of caretakerd itself.

• Optimized for containerization
  cratekerd was designed to be a simple and small process supervisor for containerization environment (such as Docker). It is explicitly not a replacement for host process supervisors like systemd.

• No dependencies
  Just download the binary and use it. caretakerd is a fat binary ready to use. You are not required to install environment with a lot of dependencies like Ruby, Python or Perl - caretakerd is build with Go.

• Builtin watchdog
  If a service crashes, caretakerd will restart it for you.

• Custom logging
  You can log how you want. It is possible to log to log files per service, to just one log file for all services or also direct to console. Also log rotate based on max file size and age of log files are builtin.

• Builtin cron
  Execute services when and how often you want.

• Focus on one core service
  There is always one service (the master) which all other services are life and die together. We expect that this service is the most important one and all other services have to serve him.

• Remote controllable
  caretakerd could fully controlled via caretakerctl command or REST calls via encrypted HTTPS.

Getting started

• Installing
• Configuring
• Run
• Control caretakerd with caretakerctl

Installing

Download your matching distribution files and extract it where you want.

Linux 64-Bit example:

sudo curl -SL https://github.com/echocat/caretakerd/releases/download/v0.1.7/caretakerd-linux-amd64.tar.gz \
    | tar -xz --exclude caretakerd.html -C /usr/bin

Hint: You can use exact these command to in a Dockerfile to create caretakerd in a docker container.

See Downloads for all possible download locations.

Configuring

Place your configuration file at your favorite location. Default location is:

• Linux: /etc/caretakerd.yaml
• Mac OS X: /etc/caretakerd.yaml
• Windows: C:\ProgramData\caretakerd\config.yaml

See Configuration examples for a quick start or consult Configuration structure for all possibilities.

Run

caretakerd run

Control caretakerd with caretakerctl

Precondition: RPC is enabled. See RPC enabled configuration example how to done this.

## Start a not already running service
$ caretakerctl start peasant

## Retrieve status of a service
$ caretakerctl status peasant

## Stop a not already running service
$ caretakerctl stop peasant

Downloads

• Linux: 32-Bit | 64-Bit
• Windows: 32-Bit | 64-Bit
• Mac OS X: 64-Bit
• Alternative downloads for version 0.1.7
• Archive

Commands

The way how the binary reacts depends on the command/file name it was called. A simple rename or symlink will change the behavior of the binary.

caretakerd

NAME:
   caretakerd - Simple control daemon for processes.

USAGE:
   caretakerd [global options] command ...

COMMANDS:
   run	Run caretakerd in forground.
   
GLOBAL OPTIONS:
   --config, -c "/etc/caretakerd.yaml"		Configuration file for daemon. [$CTD_CONFIG]
   --address, -a "tcp://localhost:57955"	Listen address of the daemon.
   

caretakerctl

NAME:
   caretakerctl - Remote control for caretakerd

USAGE:
   caretakerctl [global options] command ...

COMMANDS:
   config			Query whole daemon configuration.
   controlConfig		Query control configuration.
   services			Query whole daemon configuration with all its actual service stats.
   service			Query service configuration and its actual stats.
   serviceConfig		Query service configuration.
   serviceStatus, status	Query service status.
   servicePid, pid		Query service pid.
   serviceStart, start		Start a service.
   serviceRestart, restart	Restart a service.
   serviceStop, stop		Stop a service.
   serviceKill, kill		Kill a service.
   serviceSignal, signal	Send a signal to service.
   
GLOBAL OPTIONS:
   --config, -c "/etc/caretakerd.yaml"		Configuration file for control. [$CTCTL_CONFIG]
   --address, -a "tcp://localhost:57955"	Listen address of the daemon.
   --pem, -p "/var/run/caretakerd.key"		Location of PEM file which contains the private public key pair for access to the daemon.
   

caretaker

NAME:
   caretaker - Simple control daemon for processes including remote control for itself.

USAGE:
   caretaker [global options] command ...

COMMANDS:
   daemon			Run caretakerd in forground.
   config			Query whole daemon configuration.
   controlConfig		Query control configuration.
   services			Query whole daemon configuration with all its actual service stats.
   service			Query service configuration and its actual stats.
   serviceConfig		Query service configuration.
   serviceStatus, status	Query service status.
   servicePid, pid		Query service pid.
   serviceStart, start		Start a service.
   serviceRestart, restart	Restart a service.
   serviceStop, stop		Stop a service.
   serviceKill, kill		Kill a service.
   serviceSignal, signal	Send a signal to service.
   
GLOBAL OPTIONS:
   --config, -c "/etc/caretakerd.yaml"		Configuration file for daemon and control. [$CT_CONFIG]
   --address, -a "tcp://localhost:57955"	Listen address of the daemon.
   --pem, -p "/var/run/caretakerd.key"		Location of PEM file which contains the private public key pair for access to the daemon.
   

Configuration

• Examples
• Structure
• Environment Mapping

Examples

• RPC enabled
• Simple
• With cron expression

RPC enabled

# Run the service king at startup and enable rpc.
# peasant will only be started of "caretakerctl start peasant" is called.
# king will run for 120 seconds. If king is finished the whole careteakerd
# will go down.

rpc:
    enabled: true

services:
    king:
        type: master
        command: ["sleep", "120"]

    peasant:
        type: onDemand
        command: ["sleep","10"]

Simple

# Run the service king, queen and wonderland at startup.
# king will run for 120 seconds. If king is finished the whole careteakerd will
# go down and also terminate queen.
# wonderland will only be print "Follow the white rabbit." to console and exit
# imidately.

services:
    king:
        type: master
        command: ["sleep","120"]

    queen:
        command: ["sleep", "240"]

    wonderland:
        command: ["echo", "Follow the white rabbit."]

With cron expression

# Run the service king and queen at startup.
# queen will run every 5th second until king is finished.
# king will run for 120 seconds. If king is finished the whole careteakerd will
# go down.

services:
    king:
        type: master
        command: ["sleep","120"]

    queen:
        command: ["echo","Hello world from the queen!"]
        cronExpression: "0,5,10,15,20,25,30,35,40,45,50,55 * * * * *"

Structure

# (keyStore.KeyStore) Defines how the encryption of caretakerd works.
keyStore:
# (keyStore.Type) Defines the type of instance keyStore.
type: generated
# (string) Defines the pemFile which contains the key and certificate to use.
pemFile: ""
# (string) Defines some hints for instance store in format [<key:`value`>...].
hints: "algorithm:`rsa` bits:`1024`"
# (string) File where trusted certificates are stored in.
caFile: ""
# (rpc.Rpc) Defines how caretaker can controlled remotely.
rpc:
# (bool) If this is set to true it is possible to control caretakerd remotely.
enabled: false
# (values.SocketAddress) Address where caretakerd RPC interface is listen to.
listen: "tcp://localhost:57955"
# (control.Control) Defines the access rights of caretakerctl to caretakerd.
control:
# (access.Access) Configures the permission of caretakerctl to control caretakerd remotely and how to obtain the credentials for it.
access:
# (access.Type) Defines how this access will be ensured.
type: "generateToFile" (for control/caretakerctl) "none" (for services)
# (access.Permission) Defines what the control/service can do with caretakerd.
permission: "readWrite" (for control/caretakerctl) "forbidden" (for services)
# (string) In case of type = trusted from this file will the certificate read which should be trust and identifies the remote connection.
pemFile: ""
# (uint32) Permission in filesystem of the generated pem file.
pemFilePermission: 0600
# (string) If set this user owns the generated pem file.
pemFileUser: ""
# (logger.Logger) Configures the logger for caretakerd itself.
logger:
# (logger.Level) Minimal log level the logger will output its messages.
level: info
# (logger.Level) If the service prints something to stdout instance will logged with instance level.
stdoutLevel: info
# (logger.Level) If the service prints something to stderr instance will logged with instance level.
stderrLevel: error
# (string) Target file of the logger.
filename: "console"
# (int) Maximum size in megabytes of the log file before it gets rotated.
maxSizeInMb: 500
# (int) Maximum number of old log files to retain.
maxBackups: 500
# (int) Maximum number of days to retain old log files based on the timestamp encoded in their filename.
maxAgeInDays: 1
# (logger.Pattern) Pattern how to format the log messages to output with.
pattern: "%d{YYYY-MM-DD HH:mm:ss} [%-5.5p] [%c] %m%n%P{%m}"
# ([string]service.Service) Services configuration to run with caretakerd.
services:
<service name>:
# (service.Type) Defines how this service will run by caretakerd.
type: autoStart
# ([]string) The command the service process has to start with.
command: []
# ([][]string) Commands to be executed before execution of the actual command.
preCommands: []
# ([][]string) Commands to be executed after execution of the actual command.
postCommands: []
# (service.CronExpression) If configured this will trigger the service at this specific times.
cronExpression: ""
# (int) Wait before the service process will start the first time.
startDelayInSeconds: 0
# ([]int) Every of these values represents an expected success exit codes.
successExitCodes: [0]
# (int) Signal which will be send to the service when a stop is requested.
stopSignal: "TERM"
# (values.SignalTarget) Defines who have to receive the stop signal.
stopSignalTarget: "processGroup"
# ([]string) Command to be execute to stop the service.
stopCommand: []
# (int) Timeout to wait before kill the service process after a stop is requested.
stopWaitInSeconds: 30
# (string) User under which the service process will be started.
user: ""
# ([string]string) Environment variables to pass to the process.
environment: []
<environment name>:
# (bool) Pass the environment variables started with caretakerd also to the service process.
inheritEnvironment: true
# (string) Working directory to start the service process in.
directory: ""
# (values.RestartType) Configure how caretakerd will handle the end of a process.
autoRestart: onFailures
# (int) Seconds to wait before restart of a process.
restartDelayInSeconds: 5
# (access.Access) Configures the permission of this service to control caretakerd remotely and how to obtain the credentials for it.
access:
# (access.Type) Defines how this access will be ensured.
type: "generateToFile" (for control/caretakerctl) "none" (for services)
# (access.Permission) Defines what the control/service can do with caretakerd.
permission: "readWrite" (for control/caretakerctl) "forbidden" (for services)
# (string) In case of type = trusted from this file will the certificate read which should be trust and identifies the remote connection.
pemFile: ""
# (uint32) Permission in filesystem of the generated pem file.
pemFilePermission: 0600
# (string) If set this user owns the generated pem file.
pemFileUser: ""
# (logger.Logger) Configures the logger for this specific service.
logger:
# (logger.Level) Minimal log level the logger will output its messages.
level: info
# (logger.Level) If the service prints something to stdout instance will logged with instance level.
stdoutLevel: info
# (logger.Level) If the service prints something to stderr instance will logged with instance level.
stderrLevel: error
# (string) Target file of the logger.
filename: "console"
# (int) Maximum size in megabytes of the log file before it gets rotated.
maxSizeInMb: 500
# (int) Maximum number of old log files to retain.
maxBackups: 500
# (int) Maximum number of days to retain old log files based on the timestamp encoded in their filename.
maxAgeInDays: 1
# (logger.Pattern) Pattern how to format the log messages to output with.
pattern: "%d{YYYY-MM-DD HH:mm:ss} [%-5.5p] [%c] %m%n%P{%m}"

Environment mapping

There are several environment variables mapped to configuration parameters. There environment variables goes over configuration files.

Hint: Every caretakerd environment variable starts with CTD = CareTakerD

• Examples
• Services
• Global

Examples

caretakerd.yaml

services:
    king:
        type: master
        command: ["echo", "Hello world!"]
        user: king

Executions

$ caretakerd run
Hello world!

$ export CTD.king.COMMAND=whoami
$ caretakerd run
king

$ export CTD.king.USER=root
$ caretakerd run
root

Services

Global

Data Types

• Caretakerd
• access.Access
• access.Permission
• access.Type
• control.Control
• keyStore.KeyStore
• keyStore.Type
• logger.Logger
• logger.Level
• logger.Pattern
• rpc.Rpc
• service.Service
• service.CronExpression
• service.Type
• values.RestartType
• values.SignalTarget
• values.SocketAddress

LOG debug Message 1
LOG warn Message 2

2016-01-09 14:59:30 [DEBUG] Message 1
2016-01-09 14:59:31 [WARN ] Message 2

@every <duration>

Support

If you need support you can file a ticket at our issue tracker or join our chat at gitter.im/echocat/caretakerd.

Contributing

caretakerd is an open source project of echocat. So if you want to make this project even better, you can contribute to this project on Github by fork us.

License

caretakerd
The MIT License (MIT)

Copyright (c) echocat

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.