executor

Documentation

Overview

Package executor is used to invoke child processes across various operating systems in a way that provides the following features:

- Least privilege - Resource constraints - Process isolation

An operating system may be something like "windows" or "linux with systemd". Executors allow drivers like `exec` and `java` to share an implementation for isolation capabilities on a particular operating system.

For example:

- `exec` and `java` on Linux use a cgroups executor - `exec` and `java` on FreeBSD use a jails executor

However, drivers that provide their own isolation should not use executors. For example, using an executor to start QEMU means that the QEMU call is run inside a chroot+cgroup, even though the VM already provides isolation for the task running inside it. This is an extraneous level of indirection.

Index

• func SetCommand(e Executor, name string, args []string)
• type BasicExecutor
  • func (e *BasicExecutor) Command() *exec.Cmd
  • func (e *BasicExecutor) ConfigureTaskDir(taskName string, alloc *allocdir.AllocDir) error
  • func (e *BasicExecutor) ForceStop() error
  • func (e *BasicExecutor) ID() (string, error)
  • func (e *BasicExecutor) Limit(resources *structs.Resources) error
  • func (e *BasicExecutor) Open(id string) error
  • func (e *BasicExecutor) Shutdown() error
  • func (e *BasicExecutor) Start() error
  • func (e *BasicExecutor) Wait() *cstructs.WaitResult
• type ExecLinuxID
• type Executor
  • func Command(name string, args ...string) Executor
  • func NewBasicExecutor() Executor
  • func NewExecutor() Executor
  • func NewLinuxExecutor() Executor
  • func OpenId(id string) (Executor, error)
• type LinuxExecutor
  • func (e *LinuxExecutor) Command() *exec.Cmd
  • func (e *LinuxExecutor) ConfigureTaskDir(taskName string, alloc *allocdir.AllocDir) error
  • func (e *LinuxExecutor) ForceStop() error
  • func (e *LinuxExecutor) ID() (string, error)
  • func (e *LinuxExecutor) Limit(resources *structs.Resources) error
  • func (e *LinuxExecutor) Open(id string) error
  • func (e *LinuxExecutor) Shutdown() error
  • func (e *LinuxExecutor) Start() error
  • func (e *LinuxExecutor) Wait() *cstructs.WaitResult

Functions

func SetCommand

func SetCommand(e Executor, name string, args []string)

Types

type BasicExecutor

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

BasicExecutor should work everywhere, and as a result does not include any resource restrictions or runas capabilities.

func (*BasicExecutor) Command

func (e *BasicExecutor) Command() *exec.Cmd

func (*BasicExecutor) ConfigureTaskDir

func (e *BasicExecutor) ConfigureTaskDir(taskName string, alloc *allocdir.AllocDir) error

func (*BasicExecutor) ForceStop

func (e *BasicExecutor) ForceStop() error

func (*BasicExecutor) ID

func (e *BasicExecutor) ID() (string, error)

func (*BasicExecutor) Limit

func (e *BasicExecutor) Limit(resources *structs.Resources) error

func (*BasicExecutor) Open

func (e *BasicExecutor) Open(id string) error

func (*BasicExecutor) Shutdown

func (e *BasicExecutor) Shutdown() error

func (*BasicExecutor) Start

func (e *BasicExecutor) Start() error

func (*BasicExecutor) Wait

func (e *BasicExecutor) Wait() *cstructs.WaitResult

type ExecLinuxID

type ExecLinuxID struct {
	Groups  *cgroupConfig.Cgroup
	Spawn   *spawn.Spawner
	TaskDir string
}

execLinuxID contains the necessary information to reattach to an executed process and cleanup the created cgroups.

type Executor

type Executor interface {
	// Limit must be called before Start and restricts the amount of resources
	// the process can use. Note that an error may be returned ONLY IF the
	// executor implements resource limiting. Otherwise Limit is ignored.
	Limit(*structs.Resources) error

	// ConfigureTaskDir must be called before Start and ensures that the tasks
	// directory is properly configured.
	ConfigureTaskDir(taskName string, alloc *allocdir.AllocDir) error

	// Start the process. This may wrap the actual process in another command,
	// depending on the capabilities in this environment. Errors that arise from
	// Limits or Runas may bubble through Start()
	Start() error

	// Open should be called to restore a previous execution. This might be needed if
	// nomad is restarted.
	Open(string) error

	// Wait waits till the user's command is completed.
	Wait() *cstructs.WaitResult

	// Returns a handle that is executor specific for use in reopening.
	ID() (string, error)

	// Shutdown should use a graceful stop mechanism so the application can
	// perform checkpointing or cleanup, if such a mechanism is available.
	// If such a mechanism is not available, Shutdown() should call ForceStop().
	Shutdown() error

	// ForceStop will terminate the process without waiting for cleanup. Every
	// implementations must provide this.
	ForceStop() error

	// Command provides access the underlying Cmd struct in case the Executor
	// interface doesn't expose the functionality you need.
	Command() *exec.Cmd
}

Executor is an interface that any platform- or capability-specific exec wrapper must implement. You should not need to implement a Java executor. Rather, you would implement a cgroups executor that the Java driver will use.

func Command

func Command(name string, args ...string) Executor

Command is a mirror of exec.Command that returns a platform-specific Executor

func NewBasicExecutor

func NewBasicExecutor() Executor

func NewExecutor

func NewExecutor() Executor

func NewLinuxExecutor

func NewLinuxExecutor() Executor

func OpenId

func OpenId(id string) (Executor, error)

OpenId is similar to executor.Command but will attempt to reopen with the passed ID.

type LinuxExecutor

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

Linux executor is designed to run on linux kernel 2.8+.

func (*LinuxExecutor) Command

func (e *LinuxExecutor) Command() *exec.Cmd

func (*LinuxExecutor) ConfigureTaskDir

func (e *LinuxExecutor) ConfigureTaskDir(taskName string, alloc *allocdir.AllocDir) error

ConfigureTaskDir creates the necessary directory structure for a proper chroot. cleanTaskDir should be called after.

func (*LinuxExecutor) ForceStop

func (e *LinuxExecutor) ForceStop() error

ForceStop immediately exits the user process and cleans up both the task directory and the cgroups.

func (*LinuxExecutor) ID

func (e *LinuxExecutor) ID() (string, error)

func (*LinuxExecutor) Limit

func (e *LinuxExecutor) Limit(resources *structs.Resources) error

func (*LinuxExecutor) Open

func (e *LinuxExecutor) Open(id string) error

func (*LinuxExecutor) Shutdown

func (e *LinuxExecutor) Shutdown() error

Shutdown sends the user process an interrupt signal indicating that it is about to be forcefully shutdown in sometime

func (*LinuxExecutor) Start

func (e *LinuxExecutor) Start() error

func (*LinuxExecutor) Wait

func (e *LinuxExecutor) Wait() *cstructs.WaitResult

Wait waits til the user process exits and returns an error on non-zero exit codes. Wait also cleans up the task directory and created cgroups.