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

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

System.LXC.Internal.Container

Description

Internal module to provide a set of functions to create, control and manage LXC containers. Normally you should import System.LXC module only.

Synopsis

Documentation

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.

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.

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

newtype Container Source

Container object.

Constructors

Container 

Fields

getContainer :: Ptr C'lxc_container

A pointer to lxc_container structure.

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.

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

withC'bdev_specs :: BDevSpecs -> (Ptr C'bdev_specs -> IO a) -> IO a Source

Marshal Haskell BDevSpecs into C structure using temporary storage.

  • the memory is freed when the subcomputation terminates (either normally or via an exception), so the pointer to the temporary storage must not be used after this.

mkContainer Source

Arguments

:: String

Name to use for the container.

-> Maybe FilePath

Full path to configuration file to use.

-> IO Container

Newly allocated container.

Allocate a new container.

type Field s a = Ptr s -> Ptr a Source

mkFn :: (t -> Ptr s) -> (FunPtr (Ptr s -> a) -> Ptr s -> a) -> Field s (FunPtr (Ptr s -> a)) -> t -> IO a Source

getDaemonize :: Container -> IO Bool Source

Whether container wishes to be daemonized.

getLastError :: Container -> IO (Maybe LXCError) Source

Get last container's error.

isDefined :: Container -> IO Bool Source

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

True if container is defined, else False.

isRunning :: Container -> IO Bool Source

Determine if container is running.

True on success, else False.

state :: Container -> IO ContainerState Source

Determine state of container.

freeze :: Container -> IO Bool Source

Freeze running container.

True on success, else False.

unfreeze :: Container -> IO Bool Source

Thaw a frozen container.

True on success, else False.

initPID :: Container -> IO (Maybe ProcessID) Source

Determine process ID of the containers init process.

loadConfig Source

Arguments

:: Container

Container.

-> Maybe FilePath

Full path to alternate configuration file, or Nothing to use the default configuration file.

-> IO Bool

True on success, else False.

Load the specified configuration for the container.

start Source

Arguments

:: Container

Container.

-> Bool

Use lxcinit rather than /sbin/init.

-> [String]

Array of arguments to pass to init.

-> IO Bool

True on success, else False.

Start the container.

stop :: Container -> IO Bool Source

Stop the container.

True on success, else False.

wantDaemonize Source

Arguments

:: Container

Container.

-> Bool

Value for the daemonize bit.

-> IO Bool

True if container wants to be daemonised, else False.

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

wantCloseAllFDs Source

Arguments

:: Container

Container.

-> Bool

Value for the close_all_fds bit.

-> IO Bool

True if container wants to be daemonised, else False.

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

configFileName :: Container -> IO (Maybe FilePath) Source

Return current config file name.

wait Source

Arguments

:: Container

Container.

-> ContainerState

State to wait for.

-> Int

Timeout in seconds.

-> IO 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.

setConfigItem Source

Arguments

:: Container

Container.

-> String

Name of option to set.

-> String

Value to set.

-> IO Bool

True on success, else False.

Set a key/value configuration option.

destroy :: Container -> IO Bool Source

Delete the container.

True on success, else False.

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

saveConfig Source

Arguments

:: Container

Container.

-> FilePath

Full path to file to save configuration in.

-> IO Bool

True on success, else False.

Save configuaration to a file.

rename Source

Arguments

:: Container

Container.

-> String

New name to be used for the container.

-> IO Bool

True on success, else False.

Rename a container.

reboot :: Container -> IO Bool Source

Request the container reboot by sending it SIGINT.

True if reboot request successful, else False.

shutdown Source

Arguments

:: Container

Container.

-> Int

Seconds to wait before returning false. (-1 to wait forever, 0 to avoid waiting).

-> IO Bool

True if the container was shutdown successfully, else False.

Request the container shutdown by sending it SIGPWR.

clearConfig :: Container -> IO () Source

Completely clear the containers in-memory configuration.

getConfigItem Source

Arguments

:: Container

Container.

-> String

Name of option to get.

-> IO (Maybe String)

The item or Nothing on error.

Retrieve the value of a config item.

getRunningConfigItem Source

Arguments

:: Container

Container.

-> String

Name of option to get.

-> IO (Maybe String)

The item or Nothing on error.

Retrieve the value of a config item from running container.

getKeys Source

Arguments

:: Container

Container.

-> String

Key prefix.

-> IO [String]

List of keys.

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

getInterfaces :: Container -> IO [String] Source

Obtain a list of network interfaces.

getIPs Source

Arguments

:: Container

Container.

-> String

Network interface name to consider.

-> String

Network family (for example "inet", "inet6").

-> Word32

IPv6 scope id (ignored if family is not "inet6").

-> IO [String]

A list of network interfaces.

Determine the list of container IP addresses.

getCGroupItem Source

Arguments

:: Container

Container.

-> String

cgroup subsystem to retrieve.

-> IO (Maybe String)

cgroup subsystem value or Nothing on error.

Retrieve the specified cgroup subsystem value for the container.

setCGroupItem Source

Arguments

:: Container

Container.

-> String

cgroup subsystem to consider.

-> String

Value to set.

-> IO Bool

True on success, else False.

Set the specified cgroup subsystem value for the container.

clearConfigItem Source

Arguments

:: Container

Container.

-> String

Name of option to clear.

-> IO Bool

True on success, else False.

Clear a configuration item.

Analog of setConfigItem.

getConfigPath :: Container -> IO 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

:: Container

Container.

-> FilePath

Full path to configuration file.

-> IO Bool

True on success, else False.

Set the full path to the containers configuration file.

clone Source

Arguments

:: Container

Original container.

-> 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.

-> IO Container 

Copy a stopped container.

consoleGetFD Source

Arguments

:: Container

Container.

-> Maybe Int

Terminal number to attempt to allocate, or Nothing to allocate the first available tty.

-> IO (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

:: Container

Container.

-> 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', ...).

-> IO Bool

True on success, else False.

Allocate and run a console tty.

attach Source

Arguments

:: Container

Container.

-> AttachExecFn

Function to run.

-> AttachCommand

Data to pass to exec function.

-> AttachOptions

Attach options.

-> IO (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

:: Container

Container.

-> AttachOptions

Attach options.

-> String

Full path inside container of program to run.

-> [String]

Array of arguments to pass to program.

-> IO (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.

snapshot Source

Arguments

:: Container

Container.

-> FilePath

Full path to file containing a description of the snapshot.

-> IO (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 :: Container -> IO [Snapshot] Source

Obtain a list of container snapshots.

snapshotRestore Source

Arguments

:: Container

Container.

-> String

Name of snapshot.

-> String

Name to be used for the restored snapshot.

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

Arguments

:: Container

Container.

-> String

Name of snapshot.

-> IO Bool

True on success, else False.

Destroy the specified snapshot.

mayControl :: Container -> IO 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

:: Container

Container.

-> FilePath

Full path of the device.

-> Maybe FilePath

Alternate path in the container (or Nothing to use source path).

-> IO Bool

True on success, else False.

Add specified device to the container.

removeDeviceNode Source

Arguments

:: Container

Container.

-> FilePath

Full path of the device.

-> Maybe FilePath

Alternate path in the container (or Nothing to use source path).

-> IO Bool

True on success, else False.

Remove specified device from the container.

create Source

Arguments

:: Container

Container (with lxcpath, name and a starting configuration set).

-> 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.

-> IO Bool

True on success. False otherwise.

Create a container.

getRef :: Container -> IO Bool Source

Add a reference to the specified container.

dropRef :: Container -> IO (Maybe Bool) Source

Drop a reference to the specified container.

Just False on success, Just True if reference was successfully dropped and container has been freed, and Nothing on error.

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.

listDefinedContainers Source

Arguments

:: Maybe String

lxcpath under which to look.

-> IO [(String, 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 [(String, 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 [(String, Container)]

List of container pairs.

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

logClose :: IO () Source

Close log file.