capabilities

Documentation

Overview

Package capabilities is used for managing sets of linux capabilities.

Index

• Constants
• func Calculate(basis *Set, allowCaps, capAdd, capDrop []string) ([]string, error)
• func Delta(basis *Set, allowCaps, capAdd, capDrop []string) ([]string, []string, error)
• type Set
  • func DockerDefaults() *Set
  • func LegacySupported() *Set
  • func New(caps []string) *Set
  • func NomadDefaults() *Set
  • func Supported() *Set
  • func (s *Set) Add(cap string)
  • func (s *Set) Difference(b *Set) *Set
  • func (s *Set) Empty() bool
  • func (s *Set) Intersect(b *Set) *Set
  • func (s *Set) Remove(caps []string)
  • func (s *Set) Slice(upper bool) []string
  • func (s *Set) String() string
  • func (s *Set) Union(b *Set) *Set

Constants

const (
	// HCLSpecLiteral is an equivalent list to NomadDefaults, expressed as a literal
	// HCL string for use in HCL config parsing.
	HCLSpecLiteral = `` /* 141-byte string literal not displayed */
)

Functions

func Calculate

func Calculate(basis *Set, allowCaps, capAdd, capDrop []string) ([]string, error)

Calculate the resulting set of linux capabilities to enable for a task, taking into account: - default capability basis - driver allowable capabilities - task capability drops - task capability adds

Nomad establishes a standard set of enabled capabilities allowed by the task driver if allow_caps is not set. This is the same set that the task will be enabled with by default if allow_caps does not further reduce permissions, in which case the task capabilities will also be reduced accordingly.

The task will drop any capabilities specified in cap_drop, and add back capabilities specified in cap_add. The task will not be allowed to add capabilities not set in the the allow_caps setting (which by default is the same as the basis).

cap_add takes precedence over cap_drop, enabling the common pattern of dropping all capabilities, then adding back the desired smaller set. e.g.

cap_drop = ["all"]
cap_add = ["chown", "kill"]

Note that the resulting capability names are upper-cased and prefixed with "CAP_", which is the expected input for the exec/java driver implementation.

func Delta

func Delta(basis *Set, allowCaps, capAdd, capDrop []string) ([]string, []string, error)

Delta calculates the set of capabilities that must be added and dropped relative to a basis to achieve a desired result. The use case is that the docker driver assumes a default set (DockerDefault), and we must calculate what to pass into --cap-add and --cap-drop on container creation given the inputs of the docker plugin config for allow_caps, and the docker task configuration for cap_add and cap_drop. Note that the user provided cap_add and cap_drop settings are always included, even if they are redundant with the basis (maintaining existing behavior, working with existing tests).

Note that the resulting capability names are lower-cased and not prefixed with "CAP_", which is the existing style used with the docker driver implementation.

Types

type Set

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

Set represents a group linux capabilities, implementing some useful set operations, taking care of name normalization, and sentinel value expansions.

Linux capabilities can be expressed in multiple ways when working with docker and/or executor, along with Nomad configuration.

Capability names may be upper or lower case, and may or may not be prefixed with "CAP_" or "cap_". On top of that, Nomad interprets the special name "all" and "ALL" to mean "all capabilities supported by the operating system".

func DockerDefaults

func DockerDefaults() *Set

DockerDefaults is a list of Linux capabilities enabled by Docker by default and is used to compute the set of capabilities to add/drop given docker driver configuration.

https://docs.docker.com/engine/reference/run/#runtime-privilege-and-linux-capabilities

func LegacySupported

func LegacySupported() *Set

LegacySupported returns the historical set of capabilities used when a task is configured to run as root using the exec task driver. Older versions of Nomad always allowed the root user to make use of any capability. Now that the exec task driver supports configuring the allowed capabilities, operators are encouraged to explicitly opt-in to capabilities beyond this legacy set. We maintain the legacy list here, because previous versions of Nomad deferred to the capability.List library function, which adds new capabilities over time.

https://github.com/hashicorp/nomad/blob/v1.0.4/vendor/github.com/syndtr/gocapability/capability/enum_gen.go#L88

func New

func New(caps []string) *Set

New creates a new Set setting caps as the initial elements.

func NomadDefaults

func NomadDefaults() *Set

NomadDefaults is the set of Linux capabilities that Nomad enables by default. This list originates from what Docker enabled by default, but then excludes NET_RAW for security reasons.

This set is use in the as HCL configuration default, described by HCLSpecLiteral.

func Supported

func Supported() *Set

Supported returns the set of capabilities supported by the operating system.

This set will expand over time as new capabilities are introduced to the kernel and the capability library is updated (which tends to happen to keep up with run-container libraries).

Defers to a library generated from https://github.com/torvalds/linux/blob/master/include/uapi/linux/capability.h

func (*Set) Add

func (s *Set) Add(cap string)

Add cap into s.

func (*Set) Difference

func (s *Set) Difference(b *Set) *Set

Difference returns the Set of elements of b not in s.

func (*Set) Empty

func (s *Set) Empty() bool

Empty return true if no capabilities exist in s.

func (*Set) Intersect

func (s *Set) Intersect(b *Set) *Set

Intersect returns the Set of elements in both s and b.

func (*Set) Remove

func (s *Set) Remove(caps []string)

Remove caps from s.

func (*Set) Slice

func (s *Set) Slice(upper bool) []string

Slice returns a sorted slice of capabilities in s.

upper - indicates whether to uppercase and prefix capabilities with CAP_

func (*Set) String

func (s *Set) String() string

String returns the normalized and sorted string representation of s.

func (*Set) Union

func (s *Set) Union(b *Set) *Set

Union returns of Set of elements of both s and b.