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

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

type ContainerCreateFn = Ptr C'lxc_container -> CString -> CString -> Ptr C'bdev_specs -> CInt -> Ptr CString -> IO CBool

mkCreateFn :: FunPtr ContainerCreateFn -> ContainerCreateFn

type ContainerCloneFn = Ptr C'lxc_container -> CString -> CString -> CInt -> CString -> CString -> C'uint64_t -> Ptr CString -> IO (Ptr C'lxc_container)

mkCloneFn :: FunPtr ContainerCloneFn -> ContainerCloneFn

type ContainerBoolFn = Ptr C'lxc_container -> IO CBool

mkBoolFn :: FunPtr ContainerBoolFn -> ContainerBoolFn

type ContainerStringFn = Ptr C'lxc_container -> IO CString

mkStringFn :: FunPtr ContainerStringFn -> ContainerStringFn

type ContainerProcessIDFn = Ptr C'lxc_container -> IO C'pid_t

mkProcessIDFn :: FunPtr ContainerProcessIDFn -> ContainerProcessIDFn

type ContainerStringBoolFn = Ptr C'lxc_container -> CString -> IO CBool

mkStringBoolFn :: FunPtr ContainerStringBoolFn -> ContainerStringBoolFn

type ContainerBoolBoolFn = Ptr C'lxc_container -> CBool -> IO CBool

mkBoolBoolFn :: FunPtr ContainerBoolBoolFn -> ContainerBoolBoolFn

type ContainerStartFn = Ptr C'lxc_container -> CInt -> Ptr CString -> IO CBool

mkStartFn :: FunPtr ContainerStartFn -> ContainerStartFn

type ContainerShutdownFn = Ptr C'lxc_container -> CInt -> IO CBool

mkShutdownFn :: FunPtr ContainerShutdownFn -> ContainerShutdownFn

type ContainerClearConfigFn = Ptr C'lxc_container -> IO ()

mkClearConfigFn :: FunPtr ContainerClearConfigFn -> ContainerClearConfigFn

type ContainerGetRunningConfigItemFn = Ptr C'lxc_container -> CString -> IO CString

mkGetRunningConfigItemFn :: FunPtr ContainerGetRunningConfigItemFn -> ContainerGetRunningConfigItemFn

type ContainerGetItemFn = Ptr C'lxc_container -> CString -> CString -> CInt -> IO CInt

mkGetItemFn :: FunPtr ContainerGetItemFn -> ContainerGetItemFn

type ContainerSetItemFn = Ptr C'lxc_container -> CString -> CString -> IO CBool

mkSetItemFn :: FunPtr ContainerSetItemFn -> ContainerSetItemFn

type ContainerGetInterfacesFn = Ptr C'lxc_container -> IO (Ptr CString)

mkGetInterfacesFn :: FunPtr ContainerGetInterfacesFn -> ContainerGetInterfacesFn

type ContainerGetIPsFn = Ptr C'lxc_container -> CString -> CString -> CInt -> IO (Ptr CString)

mkGetIPsFn :: FunPtr ContainerGetIPsFn -> ContainerGetIPsFn

type ContainerWaitFn = Ptr C'lxc_container -> CString -> CInt -> IO CBool

mkWaitFn :: FunPtr ContainerWaitFn -> ContainerWaitFn

type ContainerSnapshotFn = Ptr C'lxc_container -> CString -> IO CInt

mkSnapshotFn :: FunPtr ContainerSnapshotFn -> ContainerSnapshotFn

type ContainerSnapshotListFn = Ptr C'lxc_container -> Ptr (Ptr C'lxc_snapshot) -> IO CInt

mkSnapshotListFn :: FunPtr ContainerSnapshotListFn -> ContainerSnapshotListFn

type ContainerConsoleGetFDFn = Ptr C'lxc_container -> Ptr CInt -> Ptr CInt -> IO CInt

mkConsoleGetFDFn :: FunPtr ContainerConsoleGetFDFn -> ContainerConsoleGetFDFn

type ContainerConsoleFn = Ptr C'lxc_container -> CInt -> CInt -> CInt -> CInt -> CInt -> IO CInt

mkConsoleFn :: FunPtr ContainerConsoleFn -> ContainerConsoleFn

type ContainerAttachFn = Ptr C'lxc_container -> C_lxc_attach_exec_t -> Ptr () -> Ptr C'lxc_attach_options_t -> Ptr C'pid_t -> IO CInt

mkAttachFn :: FunPtr ContainerAttachFn -> ContainerAttachFn

type ContainerAttachRunWaitFn = Ptr C'lxc_container -> Ptr C'lxc_attach_options_t -> CString -> Ptr CString -> IO CInt

mkAttachRunWaitFn :: FunPtr ContainerAttachRunWaitFn -> ContainerAttachRunWaitFn

type SnapshotFreeFn = Ptr C'lxc_snapshot -> IO ()

mkFreeFn :: FunPtr SnapshotFreeFn -> SnapshotFreeFn

newtype LXC a

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

Run LXC a computations using withContainer.

Constructors

LXC
Fields runLXC :: ReaderT (String, Ptr C'lxc_container) IO a

Instances

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

lxc :: (Ptr C'lxc_container -> IO a) -> LXC a

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

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.

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 Container

Container object.

Constructors

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

Instances

Show Container

newC'lxc_container :: Container -> IO (Ptr C'lxc_container)

Allocate a new lxc_container.

peekC'lxc_container :: Ptr C'lxc_container -> IO (String -> Container)

withC'lxc_container :: Container -> (Ptr C'lxc_container -> IO a) -> IO a

Marshal Container to lxc_container using temporary storage.

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.

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

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

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.

type Field s a = Ptr s -> Ptr a

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

boolFn :: Field C'lxc_container (FunPtr ContainerBoolFn) -> LXC Bool

stringBoolFn :: Field C'lxc_container (FunPtr ContainerStringBoolFn) -> Maybe String -> LXC Bool

boolBoolFn :: Field C'lxc_container (FunPtr ContainerBoolBoolFn) -> Bool -> LXC Bool

getItemFn :: Field C'lxc_container (FunPtr ContainerGetItemFn) -> String -> LXC (Maybe String)

setItemFn :: Field C'lxc_container (FunPtr ContainerSetItemFn) -> String -> Maybe String -> LXC Bool

setItemFn' :: Field C'lxc_container (FunPtr ContainerSetItemFn) -> String -> String -> LXC Bool

getDaemonize :: LXC Bool

Whether container wishes to be daemonized.

getLastError :: LXC (Maybe LXCError)

Get last container's error.

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.

freeze :: LXC Bool

Freeze running container.

True on success, else False.

unfreeze :: LXC Bool

Thaw a frozen container.

True on success, else False.

initPID :: LXC (Maybe ProcessID)

Determine process ID of the containers init process.

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.

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.

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.

configFileName :: LXC (Maybe FilePath)

Return current config file name.

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.

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.

destroy :: LXC Bool

Delete the container.

True on success, else False.

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

saveConfig

Arguments

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

Save configuaration to a file.

rename

Arguments

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

Rename a container.

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.

clearConfig :: LXC ()

Completely clear the containers in-memory configuration.

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.

getKeys

Arguments

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

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

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.

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.

clearConfigItem

Arguments

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

Clear a configuration item.

Analog of setConfigItem.

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.

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.

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

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.

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.

peekC'lxc_snapshot :: Ptr C'lxc_snapshot -> IO Snapshot

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.

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

Remove specified device from the container.

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.

getRef :: Ptr C'lxc_container -> IO Bool

Add a reference to the specified container.

dropRef :: Ptr C'lxc_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.

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.

listContainersFn :: (CString -> Ptr (Ptr CString) -> Ptr (Ptr (Ptr C'lxc_container)) -> IO CInt) -> Maybe String -> IO [Container]

listDefinedContainers

Arguments

:: Maybe String	lxcpath under which to look.
-> IO [Container]	List of container pairs.

Get a list of defined containers in a lxcpath.

listActiveContainers

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

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.

logClose :: IO ()

Close log file.