Copyright	(c) Nickolay Kudasov 2014
License	BSD-style (see the file LICENSE)
Maintainer	nickolay.kudasov@gmail.com
Safe Haskell	None
Language	Haskell2010

System.LXC.Container

Contents

LXC Monad
Data types
Flags
LXC errors
Container methods
Global LXC functions
- List containers
- Misc

Description

This module provides a set of functions to create, control and manage LXC containers. You can get more info about LXC at https://help.ubuntu.com/lts/serverguide/lxc.html and https://linuxcontainers.org.

Normally you should import System.LXC module only.

Synopsis

LXC Monad

Custom comment for LXC.

data LXC a

LXC container-related computations. LXC ~ ReaderT (String, Ptr C'lxc_container) IO.

Run LXC a computations using withContainer.

Instances

Monad LXC
Functor LXC
Applicative LXC
MonadIO LXC
MonadReader (String, Ptr C'lxc_container) LXC

withContainer :: MonadIO m => Container -> LXC a -> m a

Run LXC a computation for a given Container.

for the whole computation a single lxc_container structure will be allocated; it will be automatically freed at the end of computation.

Data types

data Container

Container object.

Constructors

Container
Fields containerName :: String Container name. containerConfigPath :: Maybe String Container config path.

Instances

Show Container

data Snapshot

An LXC container snapshot.

Constructors

Snapshot
Fields snapshotName :: String Name of snapshot. snapshotCommentPathname :: Maybe FilePath Full path to snapshots comment file. snapshotTimestamp :: String Time snapshot was created. snapshotLXCPath :: FilePath Full path to `LXCPATH` for snapshot.

Instances

Show Snapshot

data BDevSpecs

Specifications for how to create a new backing store.

Constructors

BDevSpecs
Fields bdevFSType :: String Filesystem type. bdevFSSize :: Word64 Filesystem size in bytes. bdevZFSRootPath :: FilePath ZFS root path. bdevLVMVolumeGroupName :: String LVM Volume Group name. bdevLVMLogicalVolumeName :: String LVM Logical Volume name. bdevLVMThinPool :: Maybe String LVM thin pool to use, if any. bdevDirectory :: FilePath Directory path.

Instances

Show BDevSpecs

data ContainerState

Container state.

Constructors

ContainerStopped	Container is stopped.
ContainerStarting	Container is starting.
ContainerRunning	Container is running.
ContainerStopping	Container is stopping.
ContainerAborting	Container is aborting.
ContainerFreezing	Container is freezing.
ContainerFrozen	Container is frozen.
ContainerThawed	Container is thawed.
ContainerOtherState String	Container is in some other state.

Instances

Eq ContainerState
Show ContainerState

parseState :: String -> ContainerState

Parse state as string representation.

printState :: ContainerState -> String

Get string representation of a state.

Flags

data CloneOption

Options for clone operation.

Constructors

CloneKeepName	Do not edit the rootfs to change the hostname.
CloneKeepMacAddr	Do not change the MAC address on network interfaces.
CloneSnapshot	Snapshot the original filesystem(s).
CloneKeepBDevType	Use the same bdev type.
CloneMaybeSnapshot	Snapshot only if bdev supports it, else copy.
CloneMaxFlags	Number of `LXC_CLONE_*` flags.

Instances

Eq CloneOption
Ord CloneOption

data CreateOption

Options for create operation.

Constructors

CreateQuiet	Redirect `stdin` to `/dev/zero` and `stdout` and `stderr` to `/dev/null`.
CreateMaxFlags	Number of `LXC_CREATE*` flags.

Instances

Eq CreateOption
Ord CreateOption

cloneFlag :: Num a => CloneOption -> a

Turn CloneOption into a bit flag.

createFlag :: Num a => CreateOption -> a

Turn CreateOption into a bit flag.

LXC errors

data LXCError

LXC error structure.

Constructors

LXCError
Fields lxcErrorString :: String Error message. lxcErrorNum :: Int Error number.

Instances

Show LXCError

prettyLXCError :: LXCError -> String

Pretty print LXC error message.

Container methods

Query container state.

isDefined :: LXC Bool

Determine if /var/lib/lxc/$name/config exists.

True if container is defined, else False.

isRunning :: LXC Bool

Determine if container is running.

True on success, else False.

state :: LXC ContainerState

Determine state of container.

initPID :: LXC (Maybe ProcessID)

Determine process ID of the containers init process.

getInterfaces :: LXC [String]

Obtain a list of network interfaces.

getIPs

Arguments

:: String	Network interface name to consider.
-> String	Network family (for example `"inet"`, `"inet6"`).
-> Word32	IPv6 scope id (ignored if family is not "inet6").
-> LXC [String]	A list of network interfaces.

Determine the list of container IP addresses.

getDaemonize :: LXC Bool

Whether container wishes to be daemonized.

getLastError :: LXC (Maybe LXCError)

Get last container's error.

Container config

configFileName :: LXC (Maybe FilePath)

Return current config file name.

getConfigPath :: LXC FilePath

Determine full path to the containers configuration file.

Each container can have a custom configuration path. However by default it will be set to either the LXCPATH configure variable, or the lxcpath value in the LXC_GLOBAL_CONF configuration file (i.e. /etc/lxc/lxc.conf).

The value for a specific container can be changed using setConfigPath.

setConfigPath

Arguments

:: FilePath	Full path to configuration file.
-> LXC Bool	`True` on success, else `False`.

Set the full path to the containers configuration file.

loadConfig

Arguments

:: Maybe FilePath	Full path to alternate configuration file, or `Nothing` to use the default configuration file.
-> LXC Bool	`True` on success, else `False`.

Load the specified configuration for the container.

saveConfig

Arguments

:: FilePath	Full path to file to save configuration in.
-> LXC Bool	`True` on success, else `False`.

Save configuaration to a file.

getKeys

Arguments

:: String	Key prefix.
-> LXC [String]	List of keys.

Retrieve a list of config item keys given a key prefix.

setConfigItem

Arguments

:: String	Name of option to set.
-> String	Value to set.
-> LXC Bool	`True` on success, else `False`.

Set a key/value configuration option.

getConfigItem

Arguments

:: String	Name of option to get.
-> LXC (Maybe String)	The item or `Nothing` on error.

Retrieve the value of a config item.

getRunningConfigItem

Arguments

:: String	Name of option to get.
-> LXC (Maybe String)	The item or `Nothing` on error.

Retrieve the value of a config item from running container.

clearConfig :: LXC ()

Completely clear the containers in-memory configuration.

clearConfigItem

Arguments

:: String	Name of option to clear.
-> LXC Bool	`True` on success, else `False`.

Clear a configuration item.

Analog of setConfigItem.

Control container state

start

Arguments

:: Bool	Use `lxcinit` rather than `/sbin/init`.
-> [String]	Array of arguments to pass to init.
-> LXC Bool	`True` on success, else `False`.

Start the container.

stop :: LXC Bool

Stop the container.

True on success, else False.

reboot :: LXC Bool

Request the container reboot by sending it SIGINT.

True if reboot request successful, else False.

shutdown

Arguments

:: Int	Seconds to wait before returning false. (`-1` to wait forever, `0` to avoid waiting).
-> LXC Bool	`True` if the container was shutdown successfully, else `False`.

Request the container shutdown by sending it SIGPWR.

freeze :: LXC Bool

Freeze running container.

True on success, else False.

unfreeze :: LXC Bool

Thaw a frozen container.

True on success, else False.

wait

Arguments

:: ContainerState	State to wait for.
-> Int	Timeout in seconds.
-> LXC Bool	`True` if state reached within timeout, else `False`.

Wait for container to reach a particular state.

A timeout of -1 means wait forever. A timeout 0 means do not wait.

Manage containers

create

Arguments

:: String	Template to execute to instantiate the root filesystem and adjust the configuration.
-> Maybe String	Backing store type to use (if `Nothing`, `dir` type will be used by default).
-> Maybe BDevSpecs	Additional parameters for the backing store (for example LVM volume group to use).
-> [CreateOption]	`CreateOption` flags. Note: LXC 1.0 supports only `CreateQuiet` option.
-> [String]	Arguments to pass to the template.
-> LXC Bool	`True` on success. `False` otherwise.

Create a container.

clone

Arguments

:: Maybe String	New name for the container. If `Nothing`, the same name is used and a new lxcpath MUST be specified.
-> Maybe FilePath	lxcpath in which to create the new container. If `Nothing`, the original container's lxcpath will be used.
-> [CloneOption]	Additional `CloneOption` flags to change the cloning behaviour.
-> Maybe String	Optionally force the cloned bdevtype to a specified plugin. By default the original is used (subject to snapshot requirements).
-> Maybe String	Information about how to create the new storage (i.e. fstype and fsdata).
-> Maybe Word64	In case of a block device backing store, an optional size. If `Nothing`, the original backing store's size will be used if possible. Note this only applies to the rootfs. For any other filesystems, the original size will be duplicated.
-> [String]	Additional arguments to pass to the clone hook script.
-> LXC (Maybe Container)	Newly-allocated copy of container `c`, or `Nothing` on error.

Copy a stopped container.

rename

Arguments

:: String	New name to be used for the container.
-> LXC Bool	`True` on success, else `False`.

Rename a container.

destroy :: LXC Bool

Delete the container.

True on success, else False.

NOTE: Container must be stopped and have no dependent snapshots.

Console

consoleGetFD

Arguments

:: Maybe Int	Terminal number to attempt to allocate, or `Nothing` to allocate the first available tty.
-> LXC (Maybe (Int, Int, Int))	Tuple `ttynum, masterfd` where `fd` is file descriptor number, `ttynum` is terminal number and `masterfd` is file descriptor refering to the master side of the pty.

Allocate a console tty for the container.

The returned file descriptor is used to keep the tty allocated. The caller should call close(2) on the returned file descriptor when no longer required so that it may be allocated by another caller.

console

Arguments

:: Maybe Int	Terminal number to attempt to allocate, `Nothing` to allocate the first available tty or `Just 0` to allocate the console.
-> Fd	File descriptor to read input from.
-> Fd	File descriptor to write output to.
-> Fd	File descriptor to write error output to.
-> Int	The escape character (`1 == 'a'`, `2 == 'b'`, ...).
-> LXC Bool	`True` on success, else `False`.

Allocate and run a console tty.

Attach to container

attach

Arguments

:: AttachExecFn	Function to run.
-> AttachCommand	Data to pass to `exec` function.
-> AttachOptions	Attach options.
-> LXC (Maybe ProcessID)	Process ID of process running inside container `c` that is running `exec` function, or `Nothing` on error.

Create a sub-process attached to a container and run a function inside it.

attachRunWait

Arguments

:: AttachOptions	Attach options.
-> String	Full path inside container of program to run.
-> [String]	Array of arguments to pass to program.
-> LXC (Maybe ExitCode)	`waitpid(2)` status of exited process that ran program, or `Nothing` on error.

Run a program inside a container and wait for it to exit.

Snapshots

snapshot

Arguments

:: Maybe FilePath	Full path to file containing a description of the snapshot.
-> LXC (Maybe Int)	`Nothing` on error, or zero-based snapshot number.

Create a container snapshot.

Assuming default paths, snapshots will be created as /var/lib/lxc/<c>/snaps/snap<n> where <c> represents the container name and <n> represents the zero-based snapshot number.

snapshotList :: LXC [Snapshot]

Obtain a list of container snapshots.

snapshotRestore

Arguments

:: String	Name of snapshot.
-> String	Name to be used for the restored snapshot.
-> LXC Bool	`True` on success, else `False`.

Create a new container based on a snapshot.

The restored container will be a copy (not snapshot) of the snapshot, and restored in the lxcpath of the original container.

WARNING: If new name is the same as the current container name, the container will be destroyed. However, this will fail if the snapshot is overlay-based, since the snapshots will pin the original container.
NOTE: As an example, if the container exists as /var/lib/lxc/c1, snapname might be "snap0" (representing /var/lib/lxc/c1/snaps/snap0). If new name is c2, then snap0 will be copied to /var/lib/lxc/c2.

snapshotDestroy

Arguments

:: String	Name of snapshot.
-> LXC Bool	`True` on success, else `False`.

Destroy the specified snapshot.

Misc

wantDaemonize

Arguments

:: Bool	Value for the daemonize bit.
-> LXC Bool	`True` if container wants to be daemonised, else `False`.

Determine if the container wants to run disconnected from the terminal.

wantCloseAllFDs

Arguments

:: Bool	Value for the `close_all_fds` bit.
-> LXC Bool	`True` if container wants to be daemonised, else `False`.

Determine whether container wishes all file descriptors to be closed on startup.

getCGroupItem

Arguments

:: String	`cgroup` subsystem to retrieve.
-> LXC (Maybe String)	`cgroup` subsystem value or `Nothing` on error.

Retrieve the specified cgroup subsystem value for the container.

setCGroupItem

Arguments

:: String	`cgroup` subsystem to consider.
-> String	Value to set.
-> LXC Bool	`True` on success, else `False`.

Set the specified cgroup subsystem value for the container.

mayControl :: LXC Bool

Determine if the caller may control the container.

False if there is a control socket for the container monitor and the caller may not access it, otherwise returns True.

addDeviceNode

Arguments

:: FilePath	Full path of the device.
-> Maybe FilePath	Alternate path in the container (or `Nothing` to use source path).
-> LXC Bool	`True` on success, else `False`.

Add specified device to the container.

removeDeviceNode

Arguments

:: FilePath	Full path of the device.
-> Maybe FilePath	Alternate path in the container (or `Nothing` to use source path).
-> LXC Bool	`True` on success, else `False`.