jail

README

Jail

Jail provides native FreeBSD Jail syscalls in Go. As of now, FreeBSD 13.1 defines the Jail API at version 2. This is the only version supported at this time. The syscalls supported are:

• jail(2)
• jail_set(2)
• jail_get(2)
• jail_attach(2)
• jail_remove(2)

To get specifics on the syscalls themselves can be referenced here.

For examples, please reference the examples directory.

Contributing

Please feel free to open a PR!

License

Jail source code is available under the BSD 3 clause License.

Contact

@bdowns328

Image Credit

www.debarbora.com

Documentation

Overview

Package jail provides the ability to lock a process or Goroutine into a FreeBSD jail.

Index

• Constants
• Variables
• func Attach(jailID int32) error
• func Get(params Params, flags uintptr) error
• func ID(name string) (int32, error)
• func Jail(o *Opts) (int32, error)
• func Name(id int32) (string, error)
• func Remove(jailID int32) error
• func Set(params Params, flags uintptr) error
• type JailParam
• type Opts
• type Params
  • func NewParams() Params
  • func (p Params) Add(k string, v interface{}) error
  • func (p Params) Validate() error

Constants

const (
	// ErrJailPermDenied [EPERM] This process is not allowed to create a jail,
	// either because it is not the super-user, or because it would exceed the
	// jail's children.max limit.
	ErrJailPermDenied = eperm

	// ErrJailFaultOutsideOfAllocatedSpace [EFAULT] jail points to an address
	// outside the allocated address space of the process.
	ErrJailFaultOutsideOfAllocatedSpace = efault

	// ErrJailInvalidVersion [EINVAL] The version number of the argument is not
	// correct.
	ErrJailInvalidVersion = einval

	// ErrjailNoFreeJIDFound [EAGAIN] No free JID could be found.
	ErrjailNoFreeJIDFound = eagain

	// ErrJailNoSuchFileDirectory [ENOENT] No such file or directory.  A component of a specified pathname
	// did not exist, or the pathname was   an empty string.
	ErrJailNoSuchFileDirectory = enoent
)

The jail() system call will fail with one of the below errors

const (
	// ErrJailSetPermDenied [EPERM] This process is not allowed to create a jail,
	// either because it is not the super-user, or because it would exceed the
	// jail's children.max limit.
	ErrJailSetPermDenied = eperm

	// ErrJailSetPermRestricted [EPERM] A jail parameter was set to a less restrictive
	// value then the current environment.
	ErrJailSetPermRestricted = eperm

	// ErrJailSetFaultOutsideOfAllocatedSpace [EFAULT] Iov, or one of the addresses
	// contained within it, points to an address outside the allocated address space
	// of the process.
	ErrJailSetFaultOutsideOfAllocatedSpace = efault

	// ErrJailSetParamNotExist [ENOENT] The jail referred to by a jid or name parameter
	// does not exist, and the JAIL_CREATE flag is not set.
	ErrJailSetParamNotExist = enoent

	// ErrJailSetNotAccessibleProcInDiffJail [ENOENT] The jail referred to by a jid
	// is not accessible by the process, because the process is	in a different jail.
	ErrJailSetNotAccessibleProcInDiffJail = enoent

	// ErrJailSetUpdateFlagNotSet [EEXIST] The jail referred to by a jid or name
	// parameter exists, and the JAIL_UPDATE flag is not set.
	ErrJailSetUpdateFlagNotSet = eexist

	// Einval [EINVAL] A supplied parameter is the wrong size.
	ErrJailSetParamWrongSize = einval

	// ErrJailSetParamOutOfRange [EINVAL] A supplied parameter is out of range.
	ErrJailSetParamOutOfRange = einval

	// ErrJailSetStringNotNullTerminated [EINVAL] A supplied string parameter is
	// not null-terminated.
	ErrJailSetStringNotNullTerminated = einval

	// ErrJailSetUnknownParam [EINVAL] A supplied parameter name does not match
	// any known parameters.
	ErrJailSetUnknownParam = einval

	// ErrJailSetCreateOrUpdateNotSet [EINVAL] One of the JAIL_CREATE or JAIL_UPDATE
	// flags is not set.
	ErrJailSetCreateOrUpdateNotSet = einval

	// ErrJailSetNameTooLong [ENAMETOOLONG] A supplied string parameter is longer
	// than allowed.
	ErrJailSetNameTooLong = enametoolong

	// ErrJailSetNoIDsLeft [EAGAIN] There are no jail IDs left.
	ErrJailSetNoIDsLeft = eagain
)

The jail_set() system call will fail with one of the below errors

const (
	// ErrJailGetFaultOutsideOfAllocatedSpace [EFAULT] Iov, or	one of the addresses
	// contained within it, points to an address outside the allocated address space
	// of the process.
	ErrJailGetFaultOutsideOfAllocatedSpace = efault

	// ErrJailGetNotExist [ENOENT] The jail referred to by jid or name parameter
	// does not exist.
	ErrJailGetNotExist = enoent

	// ErrJailGetNotAccessibleProcInDiffJail [ENOENT] The jail referred to by a
	// jid is not accessible by the process, because the process is in a different
	// jail.
	ErrJailGetNotAccessibleProcInDiffJail = enoent

	// [ENOENT] The lastjid parameter is greater than the highest current jail ID.
	ErrJailGetParamHigherThanCurJID = enoent

	// ErrJailGetParamWrongSize [EINVAL] A supplied parameter is the wrong size.
	ErrJailGetParamWrongSize = einval

	// ErrJailGetUnknownParam [EINVAL] A supplied parameter name does not match
	// any known parameters.
	ErrJailGetUnknownParam = einval
)

The jail_get() system call will fail with one of the below errors

const (
	// CreateFlag Create a new jail. If a jid or name parameters exists, they
	// must not refer to an existing jail.
	CreateFlag = uintptr(0x01)

	// UpdateFlag Modify an existing jail. One of the jid or name parameters must
	// exist, and must refer to an existing jail. If both JAIL_CREATE and JAIL_UPDATE
	// are set, a jail will be created if it does not yet exist, and modified if
	// it does exist.
	UpdateFlag = uintptr(0x02)

	// AttachFlag In addition to creating or modifying the jail, attach the current
	// process to it, as with the jail_attach() system call.
	AttachFlag = uintptr(0x04)

	// DyingFlag Allow setting a jail that is in the process of being removed.
	DyingFlag = uintptr(0x08)

	// SetMaskFlag ...
	SetMaskFlag = uintptr(0x0f)

	// GetMaskFlag ...
	GetMaskFlag = uintptr(0x08)
)

const (
	JailRawValue    = 0x01
	JailBool        = 0x02
	JailParamNoBool = 0x04
	JailParamSys    = 0x80
)

const ErrMsgLen = 1024

const EtcdConfigFile = "/etc/jail.conf"

const MaxChildJails int64 = 999999

MaxChildJails is the maximum number of jails for the system.

Variables

var (
	// ErrJailAttachUnprivilegedUser [EPERM] A user other than the super-user
	// attempted to attach to or remove a jail.
	ErrJailAttachUnprivilegedUser = eperm

	// ErrjailAttachJIDNotExist [EINVAL] The jail specified by jid does not exist.
	ErrjailAttachJIDNotExist = einval
)

The jail_attach() and jail_remove() system calls will fail with either of the below errors

Functions

func Attach

func Attach(jailID int32) error

Attach receives a jail ID and attempts to attach the current process to that jail.

func Get

func Get(params Params, flags uintptr) error

Get retrieves a matching jail based on the provided params.

func ID

func ID(name string) (int32, error)

ID returns the JID of the corresponding jail.

func Jail

func Jail(o *Opts) (int32, error)

Jail takes the given parameters, validates, and creates a new jail.

func Name

func Name(id int32) (string, error)

Name returns the name of the corresponding jail.

func Remove

func Remove(jailID int32) error

Remove receives a jail ID and attempts to remove the associated jail.

func Set

func Set(params Params, flags uintptr) error

Set creates a new jail, or modifies an existing one, and optionally locks the current process in it.

Types

type JailParam

type JailParam struct {
	Name       string
	Value      interface{}
	ValueLen   int
	ElemLen    int
	CtlType    int
	StructType int
	Flags      int
}

JailParam

type Opts

type Opts struct {
	Version  uint32
	Path     string
	Name     string
	Hostname string
	IP4      string
	Chdir    bool
}

Opts holds the options to be passed in to create the new jail.

type Params

type Params map[string]interface{}

Params contains the individual settings passed in to either get or set a jail.

func NewParams

func NewParams() Params

NewParams creates a new value of type Params by initializing the underlying map.

func (Params) Add

func (p Params) Add(k string, v interface{}) error

Add adds the given key and value to the params map.

func (Params) Validate

func (p Params) Validate() error

Validate is used to make sure that the params assigned are indeed correct and usable. This has been exposed for a caller to do validation as well as the package interally.