psdock

README

psdock

A simple tool to launch and monitor processes.

#Installation

1. Make sure $GOPATH/bin is in your path and install godep

$ go get github.com/kr/godep  
$ export PATH=$PATH:$GOPATH/bin

1. Get psdock and install it

$ go get github.com/applidget/psdock  
$ cd $GOPATH/src/github.com/applidget/psdock  
$ make

#Usage

###Basic Psdock can launch a process very simply :

psdock --command ls

###Configuration files Configuration files can be used instead. Juste create a toml file

psdock -c config.toml

If no argument is given, psdock will automatically search for the file at /etc/psdock/psdock.conf.

Here is an example of config.toml :

Command = "nc -l 8080"
Webhook = "http://distantUrl:80"
Bindport = 8080
Logprefix= "NETCAT"

###Stdout Three types of output can be specified :

• Standard output : This is the output used if the -stdout option is not specified. The output from the process will be written on the standard output.

• Logfile : For instance, you tell psdock to write the output of the process to a file named bashLog. Log-rotation is then automatically handled : by default, log files are rotated every day, but you can tell to psdock to rotate logs every minute, every hour, or every week :

    psdock --command bash --stdout "file:///bashLog" --log-rotation "hourly"
  

  Instead of writing directly to bashLog, psdock will write the output to bashLog.YYYY-MM-DD-hh-mm.log, where the date is the creation time of this file. When its lifetime will expire, psdock will compress this file to a gzip archive named bashLog.YYYY-MM-DD-hh-mm.tar.gz and will start writing the output to a new file. Psdock also ensures that the number of archived logs will not exceed 5.

• TCP Socket : The output of the process can be send through a TCP connection :

    psdock --command bash --stdout "tcp://localhost:666"
  

###Stdin Two types of stdin can be specified :

• Standard input : This is the input used if the -stdin option is not specified. The data read on the standard input will be passed to the process.

• TCP Socket : The input of the process can be read from a TCP socket :

    psdock --command bash --stdin "tcp://localhost:666"
  

###Log Formatting You can specify a prefix for the output of the process, and set its color :

psdock --command ls --log-prefix "[PREFIX]" --log-color "red"

The color can be "black" (default), "white", "red", "green", "blue", "yellow", "cyan" or "magenta".

###Web Hook A web hook can be specified as a flag:

psdock --command "bash" --web-hook "http://distantServer:3000"

Psdock will send status informations about the process to the web hook, through a PUT HTTP request. The body will be formatted like this :

{ps: {status: stat}}

where stat can be PROCESS_STARTED, PROCESS_RUNNING or PROCESS_STOPPED.

###BindPort If the --bind-port flag is set then psdock will wait for the process to bind the port specified before sending the PROCESS_RUNNING message to the web hook :

psdock --command "nc -l 8080" --web-hook "http://distantUrl:3000" --bind-port 8080

###SetUser The process can be executed under a different user. To do so, you have to specify the username of the desired process owner :

psdock --command bash --set-user "alice"

###Environment variables You can specify the environment variables to set in the process execution context :

psdock --command bash --env-vars "LD_PRELOAD=\"/path/to/my/malloc.so\""

To specify more than one envrionment variable, separe those with commas.

#License

Psdock is licensed under the MIT license. See LICENSE for the full text.

Documentation

Index

• Constants
• func ManageSignals(p *Process)
• func NewFileLogger(fName, prfx, lRotation string, statusChannel chan ProcessStatus) (*fileLogger, error)
• func Runner()
• func SetGateway(gateway string) error
• func SetUser(newUsername string) error
• type Config
  • func ParseArgs() (*Config, error)
• type Logger
• type Notifier
  • func (n Notifier) Notify(status int) error
• type Process
  • func NewProcess(conf *Config) *Process
  • func (p *Process) SetEnvVars()
  • func (p *Process) Start()
  • func (p *Process) Terminate(nbSec int) error
• type ProcessStatus

Constants

const EOL rune = 0x0A

const PROCESS_RUNNING int = 1

const PROCESS_STARTED int = 0

const PROCESS_STOPPED int = 2

const PSDOCK_CFG_FILEPATH string = "/etc/psdock/psdock.conf"

Functions

func ManageSignals

func ManageSignals(p *Process)

ManageSignals awaits for incoming signals and triggers a http request when one is received. Signals listened to are SIGINT, SIGQUIT, SIGTERM, SIGHUP, SIGALRM and SIGPIPE

func NewFileLogger

func NewFileLogger(fName, prfx, lRotation string, statusChannel chan ProcessStatus) (*fileLogger, error)

func Runner

func Runner()

func SetGateway

func SetGateway(gateway string) error

SetNetwork sets the gateway of the container. It should only be called if psdock is used in "/sbin/init" mode

func SetUser

func SetUser(newUsername string) error

SetUser tries to change the current user to newUsername

Types

type Config

type Config struct {
	Command     string
	Args        string
	Stdout      string
	LogRotation string
	LogPrefix   string
	LogColor    string
	EnvVars     string
	BindPort    int
	WebHook     string
	Stdin       string
	UserName    string
	Gateway     string
}

command is the name of the command to be executed by psdock Config contains the result of command-line-Config parsing. args are the Config passed to this command stdout is the redirection path for the stdout/stderr of the launched process logRotation is the lifetime (in seconds) of a single log file logPrefix is the prefix for logging the output of the launched process bindPort is the port watched for binding by psdock webHook is the hook triggered by psdock in case of special events user is the UID of the user launching the process

func ParseArgs

func ParseArgs() (*Config, error)

ParseArgs parses command-line Config and returns them in an Config struct

type Logger

type Logger struct {
	// contains filtered or unexported fields
}

type Notifier

type Notifier struct {
	// contains filtered or unexported fields
}

func (Notifier) Notify

func (n Notifier) Notify(status int) error

Notify sends a PUT request to the hook in order to trigger it

type Process

type Process struct {
	Cmd   *exec.Cmd
	Conf  *Config
	Notif Notifier
	Pty   *os.File

	StatusChannel chan ProcessStatus
	// contains filtered or unexported fields
}

func NewProcess

func NewProcess(conf *Config) *Process

NewProcess creates a new struct of type *Process and returns its address

func (*Process) SetEnvVars

func (p *Process) SetEnvVars()

SetEnvVars sets the environment variables for the launched process If p.Conf.EnvVars is empty, we pass all the current env vars to the child

func (*Process) Start

func (p *Process) Start()

func (*Process) Terminate

func (p *Process) Terminate(nbSec int) error

Terminate sends a SIGTERM signal, then waits nbSec seconds before sending a SIGKILL if necessary. p.ioC.restoreIO() will be called at the end of the function

type ProcessStatus

type ProcessStatus struct {
	Status int
	Err    error
}

type used to communicate between goroutines