caretakerd

Version: 1.0.9

caretakerd is a simple process supervisor. There are no external dependencies and it is optimized for containerization (as used in Docker) and simple configuration.

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 also receive its command line from the command line of caretakerd itself.

• Optimized for containerization
  caretakerd was designed to be a simple and small process supervisor for containerization environments (such as Docker). It is no 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 an 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 to your liking. It is possible to log to files per service, to just log one file for all services or to directly log to the console. Also log rotation based on max file size and age of log files are built in.

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

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

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

Getting started

• Installing
• Configuring
• Run
• Control caretakerd with caretakerctl
• See in action with Docker

Installing

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

Linux 64-Bit example:

## Download directly from GitHub...
sudo curl -SL https://github.com/echocat/caretakerd/releases/download/v1.0.9/caretakerd-linux-amd64.tar.gz \
    | tar -xz --exclude caretakerd.html -C /usr/bin

## Download from caretakerd.echocat.org...   
sudo curl -SL https://caretakerd.echocat.org/v1.0.9/download/caretakerd-linux-amd64.tar.gz \
    | tar -xz --exclude caretakerd.html -C /usr/bin

## Download the latest version from caretakerd.echocat.org...   
sudo curl -SL https://caretakerd.echocat.org/latest/download/caretakerd-linux-amd64.tar.gz \
    | tar -xz --exclude caretakerd.html -C /usr/bin

Hint: You can use this command 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 the Configuration structure for all possibilities.

Run

caretakerd run

Control caretakerd with caretakerctl

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

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

## Retrieve the status of a service
$ caretakerctl status peasant

## Stop an already running service
$ caretakerctl stop peasant

See in action with Docker

You can find lots of working demos on github.com/echocat/caretakerd-docker-demos. Try it out!

Downloads

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

Commands

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

caretakerd

usage: caretakerd [<flags>] <command> [<args> ...]

Simple control daemon for processes.

Flags:
  -c, --config=/etc/caretakerd.yaml  
    Configuration file for daemon. ($CTD_CONFIG)
  -a, --address=tcp://localhost:57955  
    Listen address of the daemon.

Commands:
help [<command>...]
    Show help.


version
    Print the actual version and other useful information.


run [<args>...]
    Run caretakerd in foreground.

caretakerctl

usage: caretakerctl [<flags>] <command> [<args> ...]

Remote control for caretakerd

Flags:
  -c, --config=/etc/caretakerd.yaml  
    Configuration file for control. ($CTCTL_CONFIG)
  -a, --address=tcp://localhost:57955  
    Listen address of the daemon.
  -p, --pem=/var/run/caretakerd.key  
    Location of PEM file which contains the private public key pair for access
    to the daemon.

Commands:
help [<command>...]
    Show help.


version
    Print the actual version and other useful information.


config <target>
    Returns configurations for defined service, '!daemon' or '!control'.


get [<target>]
    Query states for given service or if nothing specified for all services.


status <service>
    Query status of a service.


pid <service>
    Query pid of a service.


start <service>
    Starts a service.


restart <service>
    Restarts a service.


stop <service>
    Stops a service.


kill <service>
    Kills a service.


signal <service> <signal>
    Send a signal to service.

caretaker

usage: caretaker [<flags>] <command> [<args> ...]

Simple control daemon for processes including remote control for itself.

Flags:
  -c, --config=/etc/caretakerd.yaml  
    Configuration file for daemon and control. ($CT_CONFIG)
  -a, --address=tcp://localhost:57955  
    Listen address of the daemon.
  -p, --pem=/var/run/caretakerd.key  
    Location of PEM file which contains the private public key pair for access
    to the daemon.

Commands:
help [<command>...]
    Show help.


version
    Print the actual version and other useful information.


daemon [<args>...]
    Run caretakerd in foreground.


config <target>
    Returns configurations for defined service, '!daemon' or '!control'.


get [<target>]
    Query states for given service or if nothing specified for all services.


status <service>
    Query status of a service.


pid <service>
    Query pid of a service.


start <service>
    Starts a service.


restart <service>
    Restarts a service.


stop <service>
    Stops a service.


kill <service>
    Kills a service.


signal <service> <signal>
    Send a signal to service.

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
# immediately.

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 the instance keyStore.
type: generated
# (string) Defines the pemFile which contains the key and certificate to be used.
pemFile: ""
# (string) Defines some hints, for example to store in the 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 listened 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) If the property type = trusted, the certificates specified in this file are used to trust remote connections.
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 uses to log error messages.
level: info
# (logger.Level) If the service prints something to stdout, the instance will be logged with the corresponding instance level.
stdoutLevel: info
# (logger.Level) If the service prints something to stderr, the instance will be logged with the corresponding 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 be 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 code.
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 executed to stop the service.
stopCommand: []
# (int) Timeout to wait before killing 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) Additionally pass the environment variables started with caretakerd 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) If the property type = trusted, the certificates specified in this file are used to trust remote connections.
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 uses to log error messages.
level: info
# (logger.Level) If the service prints something to stdout, the instance will be logged with the corresponding instance level.
stdoutLevel: info
# (logger.Level) If the service prints something to stderr, the instance will be logged with the corresponding 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) Contains the source where this config comes from.
-:

Environment mapping

There are several environment variables mapped to configuration parameters. These environment variables are overwriting values from 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. 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.