Safe Haskell	Safe-Inferred
Language	Haskell2010

System.LXC.Container

Contents

Data types
Flags
Container methods
Global LXC functions
- List containers
- Misc

Synopsis

Data types

newtype Container Source

Container object.

Constructors

Container
Fields getContainer :: Ptr C'lxc_container A pointer to `lxc_container` structure.

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

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.

data ContainerState Source

Constructors

ContainerStopped
ContainerStarting
ContainerRunning
ContainerStopping
ContainerAborting
ContainerFreezing
ContainerFrozen
ContainerThawed
ContainerOtherState String

Instances

Eq ContainerState
Show ContainerState

parseState :: String -> ContainerState Source

printState :: ContainerState -> String Source

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.

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.

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.

Container methods

Query container state.

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.

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

Determine process ID of the containers init process.

Container config

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

Return current config file name.

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.

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.

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.

getKeys Source

Arguments

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

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

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.

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.

clearConfig :: Container -> IO () Source

Completely clear the containers in-memory configuration.

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.

Freeze/unfreeze

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.

Control container state

start Source

Arguments

:: Container	Container.
-> Int	Use `lxcinit` rather than `sbininit`.
-> [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.

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.

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.

Manage containers

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.

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.

rename Source

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 Source

Delete the container.

True on success, else False.

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

Console

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

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.

Snapshots

snapshot :: Container -> FilePath -> IO (Maybe Int) Source

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.

Misc

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.

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.

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.

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.

Global LXC functions

List containers

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.

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.