lxc-0.3: High level Haskell bindings to LXC (Linux containers).

Copyright(c) Nickolay Kudasov 2014
LicenseBSD-style (see the file LICENSE)
Maintainernickolay.kudasov@gmail.com
Safe HaskellNone
LanguageHaskell2010

System.LXC.Container

Contents

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.

Normally you should import System.LXC module only.

Synopsis

LXC Monad

data LXC a Source

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

Run LXC a computations using withContainer.

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

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 Source

Container object.

Constructors

Container 

Fields

containerName :: String

Container name.

containerConfigPath :: Maybe String

Container config path.

Instances

data Snapshot Source

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

data BDevSpecs Source

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

data ContainerState Source

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.

parseState :: String -> ContainerState Source

Parse state as string representation.

printState :: ContainerState -> String Source

Get string representation of a state.

Flags

data CloneOption Source

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.

data CreateOption Source

Options for create operation.

Constructors

CreateQuiet

Redirect stdin to /dev/zero and stdout and stderr to /dev/null.

CreateMaxFlags

Number of LXC_CREATE* flags.

cloneFlag :: Num a => CloneOption -> a Source

Turn CloneOption into a bit flag.

createFlag :: Num a => CreateOption -> a Source

Turn CreateOption into a bit flag.

LXC errors

data LXCError Source

LXC error structure.

Constructors

LXCError 

Fields

lxcErrorString :: String

Error message.

lxcErrorNum :: Int

Error number.

Instances

prettyLXCError :: LXCError -> String Source

Pretty print LXC error message.

Container methods

Query container state.

isDefined :: LXC Bool Source

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

True if container is defined, else False.

isRunning :: LXC Bool Source

Determine if container is running.

True on success, else False.

state :: LXC ContainerState Source

Determine state of container.

initPID :: LXC (Maybe ProcessID) Source

Determine process ID of the containers init process.

getInterfaces :: LXC [String] Source

Obtain a list of network interfaces.

getIPs Source

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 Source

Whether container wishes to be daemonized.

getLastError :: LXC (Maybe LXCError) Source

Get last container's error.

Container config

configFileName :: LXC (Maybe FilePath) Source

Return current config file name.

getConfigPath :: LXC FilePath Source

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 Source

Arguments

:: FilePath

Full path to configuration file.

-> LXC Bool

True on success, else False.

Set the full path to the containers configuration file.

loadConfig Source

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 Source

Arguments

:: FilePath

Full path to file to save configuration in.

-> LXC Bool

True on success, else False.

Save configuaration to a file.

getKeys Source

Arguments

:: String

Key prefix.

-> LXC [String]

List of keys.

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

setConfigItem Source

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 Source

Arguments

:: String

Name of option to get.

-> LXC (Maybe String)

The item or Nothing on error.

Retrieve the value of a config item.

getRunningConfigItem Source

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 () Source

Completely clear the containers in-memory configuration.

clearConfigItem Source

Arguments

:: String

Name of option to clear.

-> LXC Bool

True on success, else False.

Clear a configuration item.

Analog of setConfigItem.

Freeze/unfreeze

freeze :: LXC Bool Source

Freeze running container.

True on success, else False.

unfreeze :: LXC Bool Source

Thaw a frozen container.

True on success, else False.

Control container state

start Source

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 Source

Stop the container.

True on success, else False.

reboot :: LXC Bool Source

Request the container reboot by sending it SIGINT.

True if reboot request successful, else False.

shutdown Source

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.

wait Source

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 Source

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 Source

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 Source

Arguments

:: String

New name to be used for the container.

-> LXC Bool

True on success, else False.

Rename a container.

destroy :: LXC Bool Source

Delete the container.

True on success, else False.

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

Console

consoleGetFD Source

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 Source

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 Source

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 Source

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 Source

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] Source

Obtain a list of container snapshots.

snapshotRestore Source

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.

Misc

wantDaemonize Source

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 Source

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 Source

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 Source

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 Source

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 Source

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 Source

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.

Remove specified device from the container.

Global LXC functions

List containers

listDefinedContainers Source

Arguments

:: Maybe String

lxcpath under which to look.

-> IO [Container]

List of container pairs.

Get a list of defined containers in a lxcpath.

listActiveContainers Source

Arguments

:: Maybe String

Full LXCPATH path to consider.

-> IO [Container]

List of container pairs.

Get a list of active containers for a given lxcpath.

listAllContainers Source

Arguments

:: Maybe String

Full LXCPATH path to consider.

-> IO [Container]

List of container pairs.

Get a complete list of all containers for a given lxcpath.

Misc

getWaitStates :: IO [ContainerState] Source

Obtain a list of all container states.

getGlobalConfigItem Source

Arguments

:: String

The name of the config key.

-> IO (Maybe String)

String representing the current value for the key. Nothing on error.

Get the value for a global config key.

getVersion :: IO String Source

Determine version of LXC.

logClose :: IO () Source

Close log file.