System.LXC.Container

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.

Data types

newtype Container

Container object.

Constructors

Container

Fields

getContainer :: Ptr C'lxc_container

A pointer to lxc_container structure.

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.

mkContainer

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.

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

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

True if container is defined, else False.

isRunning :: Container -> IO Bool

Determine if container is running.

True on success, else False.

state :: Container -> IO ContainerState

Determine state of container.

initPID :: Container -> IO (Maybe ProcessID)

Determine process ID of the containers init process.

getInterfaces :: Container -> IO [String]

Obtain a list of network interfaces.

getIPs

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.

getDaemonize :: Container -> IO Bool

Whether container wishes to be daemonized.

getLastError :: Container -> IO (Maybe LXCError)

Get last container's error.

Container config

configFileName :: Container -> IO (Maybe FilePath)

Return current config file name.

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

:: Container

Container.

-> FilePath

Full path to configuration file.

-> IO Bool

True on success, else False.

Set the full path to the containers configuration file.

loadConfig

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.

saveConfig

Arguments

:: Container

Container.

-> FilePath

Full path to file to save configuration in.

-> IO Bool

True on success, else False.

Save configuaration to a file.

getKeys

Arguments

:: Container

Container.

-> String

Key prefix.

-> IO [String]

List of keys.

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

setConfigItem

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.

getConfigItem

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

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.

clearConfig :: Container -> IO ()

Completely clear the containers in-memory configuration.

clearConfigItem

Arguments

:: Container

Container.

-> String

Name of option to clear.

-> IO Bool

True on success, else False.

Clear a configuration item.

Analog of setConfigItem.

Freeze/unfreeze

freeze :: Container -> IO Bool

Freeze running container.

True on success, else False.

unfreeze :: Container -> IO Bool

Thaw a frozen container.

True on success, else False.

Control container state

start

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

Stop the container.

True on success, else False.

reboot :: Container -> IO Bool

Request the container reboot by sending it SIGINT.

True if reboot request successful, else False.

shutdown

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.

wait

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.

Manage containers

create

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.

clone

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.

rename

Arguments

:: Container

Container.

-> String

New name to be used for the container.

-> IO Bool

True on success, else False.

Rename a container.

destroy :: Container -> IO Bool

Delete the container.

True on success, else False.

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

Console

consoleGetFD

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

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 to container

attach

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

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.

Snapshots

snapshot

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]

Obtain a list of container snapshots.

snapshotRestore

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.

Misc

wantDaemonize

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

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.

getCGroupItem

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

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.

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

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

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.

getRef :: Container -> IO Bool

Add a reference to the specified container.

dropRef :: Container -> IO (Maybe Bool)

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.

Global LXC functions

List containers

listDefinedContainers

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

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

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.

Misc

getWaitStates :: IO [ContainerState]

Obtain a list of all container states.

getGlobalConfigItem

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

Determine version of LXC.

logClose :: IO ()

Close log file.