Copyright	(c) Nickolay Kudasov 2014
License	BSD-style (see the file LICENSE)
Maintainer	nickolay.kudasov@gmail.com
Safe Haskell	Safe-Inferred
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 Source

mkCreateFn :: FunPtr ContainerCreateFn -> ContainerCreateFn Source

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

mkCloneFn :: FunPtr ContainerCloneFn -> ContainerCloneFn Source

type ContainerBoolFn = Ptr C'lxc_container -> IO CBool Source

mkBoolFn :: FunPtr ContainerBoolFn -> ContainerBoolFn Source

type ContainerStringFn = Ptr C'lxc_container -> IO CString Source

mkStringFn :: FunPtr ContainerStringFn -> ContainerStringFn Source

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

mkProcessIDFn :: FunPtr ContainerProcessIDFn -> ContainerProcessIDFn Source

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

mkStringBoolFn :: FunPtr ContainerStringBoolFn -> ContainerStringBoolFn Source

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

mkBoolBoolFn :: FunPtr ContainerBoolBoolFn -> ContainerBoolBoolFn Source

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

mkStartFn :: FunPtr ContainerStartFn -> ContainerStartFn Source

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

mkShutdownFn :: FunPtr ContainerShutdownFn -> ContainerShutdownFn Source

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

mkClearConfigFn :: FunPtr ContainerClearConfigFn -> ContainerClearConfigFn Source

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

mkGetRunningConfigItemFn :: FunPtr ContainerGetRunningConfigItemFn -> ContainerGetRunningConfigItemFn Source

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

mkGetItemFn :: FunPtr ContainerGetItemFn -> ContainerGetItemFn Source

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

mkSetItemFn :: FunPtr ContainerSetItemFn -> ContainerSetItemFn Source

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

mkGetInterfacesFn :: FunPtr ContainerGetInterfacesFn -> ContainerGetInterfacesFn Source

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

mkGetIPsFn :: FunPtr ContainerGetIPsFn -> ContainerGetIPsFn Source

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

mkWaitFn :: FunPtr ContainerWaitFn -> ContainerWaitFn Source

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

mkSnapshotFn :: FunPtr ContainerSnapshotFn -> ContainerSnapshotFn Source

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

mkSnapshotListFn :: FunPtr ContainerSnapshotListFn -> ContainerSnapshotListFn Source

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

mkConsoleGetFDFn :: FunPtr ContainerConsoleGetFDFn -> ContainerConsoleGetFDFn Source

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

mkConsoleFn :: FunPtr ContainerConsoleFn -> ContainerConsoleFn Source

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

mkAttachFn :: FunPtr ContainerAttachFn -> ContainerAttachFn Source

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

mkAttachRunWaitFn :: FunPtr ContainerAttachRunWaitFn -> ContainerAttachRunWaitFn Source

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

mkFreeFn :: FunPtr SnapshotFreeFn -> SnapshotFreeFn Source

data LXCError Source

LXC error structure.

Constructors

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

Instances

Show LXCError

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.

Instances

Eq CloneOption
Ord CloneOption

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.

Instances

Eq CreateOption
Ord CreateOption

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

Show Snapshot

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.

Instances

Eq ContainerState
Show ContainerState

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

Show BDevSpecs

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

boolFn :: Field C'lxc_container (FunPtr ContainerBoolFn) -> Container -> IO Bool Source

stringBoolFn :: Field C'lxc_container (FunPtr ContainerStringBoolFn) -> Container -> Maybe String -> IO Bool Source

boolBoolFn :: Field C'lxc_container (FunPtr ContainerBoolBoolFn) -> Container -> Bool -> IO Bool Source

getItemFn :: Field C'lxc_container (FunPtr ContainerGetItemFn) -> Container -> String -> IO (Maybe String) Source

setItemFn :: Field C'lxc_container (FunPtr ContainerSetItemFn) -> Container -> String -> Maybe String -> IO Bool Source

setItemFn' :: Field C'lxc_container (FunPtr ContainerSetItemFn) -> Container -> String -> String -> IO Bool 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.

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

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.

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

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.