Network.LXD.Client.Commands

This module implements commands to communicate with the LXD daemon over its REST API.

More information about LXD: https://github.com/lxc/lxd

This module implements a high-level interface, and is probably what you need. It uses the lower-level interface implemented in Network.LXD.Client.API, but unless you are a power user, you shouldn't need this module.

Accompanying blog post: https://deliquus.com/posts/2017-10-02-using-servant-to-orchestrate-lxd-containers.html

How to use this library

All commands take place in the HasClient monad. The WithLocalHost and WithRemoteHost monads can be used directly for fast access to an LXD daemon, but you can also make your own monad stack an instance of HasClient.

You can connect to an LXD daemon over a unix-socket on the local host, or over HTTPS. For more information about these connection types see Network.LXD.Client.

An example using these command to conncet to the LXD instance on your local host (should work out of the box).

{-# LANGUAGE OverloadedStrings #-}
module Main where

import Control.Monad.IO.Class (liftIO)
import Network.LXD.Client.Commands

main :: IO ()
main = runWithLocalHost def $ do
    liftIO $ putStrLn "Creating my-container"
    lxcCreate . containerCreateRequest "my-container"
              . ContainerSourceRemote
              $ remoteImage imagesRemote "ubuntu/xenial/amd64"

    liftIO $ putStrLn "Starting my-container"
    lxcStart "my-container"

    liftIO $ putStrLn "Stopping my-container"
    lxcStop "my-container" False

    liftIO $ putStrLn "Deleting my-container"
    lxcDelete "my-container"

Re-exports

def :: Default a => a

The default value for this type.

module Network.LXD.Client.Remotes

module Network.LXD.Client.Types

Running commands

data Host

A host that can be connected to.

Constructors

HLocalHost LocalHost

HRemoteHost RemoteHost

class (MonadIO m, MonadMask m) => HasClient m where

Monad with access to a ClientEnv.

Minimal complete definition

askHost

Methods

askHost :: m Host

Return the LXD remote host to connect to.

askClientEnv :: m ClientEnv

Return the ClientEnv to use when connecting to the LXD host.

Returns defaultClientEnv by default.

Instances

HasClient WithRemoteHost

Methods

askHost :: WithRemoteHost Host

askClientEnv :: WithRemoteHost ClientEnv

HasClient WithLocalHost

Methods

askHost :: WithLocalHost Host

askClientEnv :: WithLocalHost ClientEnv

defaultClientEnv :: HasClient m => m ClientEnv

Create a default ClientEnv.

data WithLocalHost a

Monad with access to a local host.

Instances

Monad WithLocalHost

Methods

(>>=) :: WithLocalHost a -> (a -> WithLocalHost b) -> WithLocalHost b

(>>) :: WithLocalHost a -> WithLocalHost b -> WithLocalHost b

return :: a -> WithLocalHost a

fail :: String -> WithLocalHost a

Functor WithLocalHost

Methods

fmap :: (a -> b) -> WithLocalHost a -> WithLocalHost b

(<$) :: a -> WithLocalHost b -> WithLocalHost a

Applicative WithLocalHost

Methods

pure :: a -> WithLocalHost a

(<*>) :: WithLocalHost (a -> b) -> WithLocalHost a -> WithLocalHost b

(*>) :: WithLocalHost a -> WithLocalHost b -> WithLocalHost b

(<*) :: WithLocalHost a -> WithLocalHost b -> WithLocalHost a

MonadIO WithLocalHost

Methods

liftIO :: IO a -> WithLocalHost a

MonadThrow WithLocalHost

Methods

throwM :: Exception e => e -> WithLocalHost a

MonadCatch WithLocalHost

Methods

catch :: Exception e => WithLocalHost a -> (e -> WithLocalHost a) -> WithLocalHost a

MonadMask WithLocalHost

Methods

mask :: ((forall a. WithLocalHost a -> WithLocalHost a) -> WithLocalHost b) -> WithLocalHost b

uninterruptibleMask :: ((forall a. WithLocalHost a -> WithLocalHost a) -> WithLocalHost b) -> WithLocalHost b

HasClient WithLocalHost

Methods

askHost :: WithLocalHost Host

askClientEnv :: WithLocalHost ClientEnv

runWithLocalHost :: LocalHost -> WithLocalHost a -> IO a

Run a WithLocalHost monad

data WithRemoteHost a

Monad with access to a remote host.

Instances

Monad WithRemoteHost

Methods

(>>=) :: WithRemoteHost a -> (a -> WithRemoteHost b) -> WithRemoteHost b

(>>) :: WithRemoteHost a -> WithRemoteHost b -> WithRemoteHost b

return :: a -> WithRemoteHost a

fail :: String -> WithRemoteHost a

Functor WithRemoteHost

Methods

fmap :: (a -> b) -> WithRemoteHost a -> WithRemoteHost b

(<$) :: a -> WithRemoteHost b -> WithRemoteHost a

Applicative WithRemoteHost

Methods

pure :: a -> WithRemoteHost a

(<*>) :: WithRemoteHost (a -> b) -> WithRemoteHost a -> WithRemoteHost b

(*>) :: WithRemoteHost a -> WithRemoteHost b -> WithRemoteHost b

(<*) :: WithRemoteHost a -> WithRemoteHost b -> WithRemoteHost a

MonadIO WithRemoteHost

Methods

liftIO :: IO a -> WithRemoteHost a

MonadThrow WithRemoteHost

Methods

throwM :: Exception e => e -> WithRemoteHost a

MonadCatch WithRemoteHost

Methods

catch :: Exception e => WithRemoteHost a -> (e -> WithRemoteHost a) -> WithRemoteHost a

MonadMask WithRemoteHost

Methods

mask :: ((forall a. WithRemoteHost a -> WithRemoteHost a) -> WithRemoteHost b) -> WithRemoteHost b

uninterruptibleMask :: ((forall a. WithRemoteHost a -> WithRemoteHost a) -> WithRemoteHost b) -> WithRemoteHost b

HasClient WithRemoteHost

Methods

askHost :: WithRemoteHost Host

askClientEnv :: WithRemoteHost ClientEnv

runWithRemoteHost :: RemoteHost -> WithRemoteHost a -> IO a

Run a WithRemoteHost monad

API

lxcApi :: HasClient m => m ApiConfig

Get information about the API.

Containers

lxcList :: HasClient m => m [ContainerName]

List all container names.

lxcCreate :: HasClient m => ContainerCreateRequest -> m ()

Create a new container.

lxcDelete :: HasClient m => ContainerName -> m ()

Delete a container.

lxcInfo :: HasClient m => ContainerName -> m Container

Get information about a container.

lxcStart :: HasClient m => ContainerName -> m ()

Start a contianer.

lxcStop :: HasClient m => ContainerName -> Bool -> m ()

Stop a container.

The second flag forces the action.

lxcRestart :: HasClient m => ContainerName -> Bool -> m ()

Restart a container.

The second flag forces the action.

lxcFreeze :: HasClient m => ContainerName -> m ()

Freeze a container.

lxcUnfreeze :: HasClient m => ContainerName -> m ()

Unfreeze a container.

Exec

lxcExec

Arguments

:: HasClient m

=> ContainerName

Container name

-> String

Command name

-> [String]

Command arguments

-> ByteString

Standard input

-> m ByteString

Execute a command, catch standard output, print stderr.

lxcExecEnv

Arguments

:: HasClient m

=> ContainerName

Container name

-> String

Command name

-> [String]

Command arguments

-> Map String String

Environment variables

-> ByteString

Standard input

-> m ByteString

Execute a command, provide environment variables, catch standard output, print stderr.

lxcExecRaw

Arguments

:: HasClient m

=> ContainerName

Container name

-> String

Command name

-> [String]

Command arguments

-> Map String String

Environment variables

-> MVar (Maybe ByteString)

Stream of standard input, pass Nothing to end the stream.

-> MVar ByteString

Standard output

-> MVar ByteString

Standard error

-> m (Async ())

Execute a command, with given environment variables.

Files and directories

Deletion

lxcFileDelete :: HasClient m => ContainerName -> FilePath -> m ()

Delete a file or empty directory from an LXD container.

Files

lxcFilePull

Arguments

:: HasClient m

=> ContainerName

Container name

-> FilePath

Source path, in the container

-> FilePath

Destination path, in the host

-> m ()

Pull the file contents from an LXD container.

lxcFilePullRaw :: HasClient m => ContainerName -> FilePath -> m ByteString

Pull the file contents from an LXD container, return the lazy bytestring.

lxcFilePush

Arguments

:: HasClient m

=> ContainerName

Container name

-> FilePath

Source path, in the host

-> FilePath

Destination path, in the container

-> m ()

Push the file contents to an LXD container.

lxcFilePushAttrs

Arguments

:: HasClient m

=> ContainerName

Container name

-> FilePath

Source path, in the host

-> FilePath

Destination path, in the container

-> Maybe Uid

-> Maybe Gid

-> m ()

Push the fole contents to an LXD container, with the given attributes.

lxcFilePushRaw :: HasClient m => ContainerName -> FilePath -> ByteString -> m ()

Write the lazy bytestring to a file in an LXD container.

lxcFilePushRawAttrs :: HasClient m => ContainerName -> FilePath -> Maybe Uid -> Maybe Gid -> Maybe FileMode -> FileType -> Maybe WriteMode -> ByteString -> m ()

Write the lazy bytestring to a file in an LXD container, with given file attributes.

Directories

lxcFileListDir :: HasClient m => ContainerName -> FilePath -> m [String]

List all entries in a directory, without . or ...

lxcFileMkdir

Arguments

:: HasClient m

=> ContainerName

-> String

-> Bool

Create parent directories

-> m ()

Create a directory.

lxcFileMkdirTemplate

Arguments

:: HasClient m

=> ContainerName

Container name

-> FilePath

Source path, in the host

-> FilePath

Destination path, in the container

-> m ()

Create a directory using a host directory as a template.

Note that this function doesn't copy the directory contents. Use lxcFilePushRecursive if you want to copy the directory contents as well.

lxcFileMkdirAttrs

Arguments

:: HasClient m

=> ContainerName

-> String

-> Bool

Create parent directories

-> Maybe Uid

-> Maybe Gid

-> Maybe FileMode

-> m ()

Create a directory, with given attributes.

Recursive

lxcFilePullRecursive

Arguments

:: HasClient m

=> ContainerName

Container name

-> FilePath

Source path, in the container

-> FilePath

Destination path, in the host

-> m ()

Recursively pull a directory (or file) from a container.

lxcFilePushRecursive

Arguments

:: HasClient m

=> ContainerName

Container name

-> FilePath

Source path, in the host

-> FilePath

Destination path, in the container

-> m ()

Recursively push a directory (or file) to a container.

lxcFilePushRecursiveAttrs

Arguments

:: HasClient m

=> ContainerName

-> FilePath

Souce path, in the host

-> FilePath

Destination path, in the container

-> Maybe Uid

-> Maybe Gid

-> m ()

Recursively push a directory (or file) to a container, with given file attributes.

Images

lxcImageList :: HasClient m => m [ImageId]

List all image IDs.

lxcImageAliases :: HasClient m => m [ImageAliasName]

List al image aliases.

lxcImageInfo :: HasClient m => ImageId -> m Image

Get image information.

lxcImageAlias :: HasClient m => ImageAliasName -> m ImageAlias

Get image alias information.

lxcImageCreate :: HasClient m => ImageCreateRequest -> m ()

Create an image.

lxcImageDelete :: HasClient m => ImageId -> m ()

Delete an image.

Networks

lxcNetworkList :: HasClient m => m [NetworkName]

List all networks

lxcNetworkCreate :: HasClient m => NetworkCreateRequest -> m ()

Create a network.

lxcNetworkInfo :: HasClient m => NetworkName -> m Network

Get network information.

lxcNetworkConfig :: HasClient m => NetworkName -> NetworkConfigRequest -> m ()

Configure a network.

lxcNetworkDelete :: HasClient m => NetworkName -> m ()

Delete a network

Profiles

lxcProfileList :: HasClient m => m [ProfileName]

List all profiles

lxcProfileCreate :: HasClient m => ProfileCreateRequest -> m ()

Create a profile.

lxcProfileInfo :: HasClient m => ProfileName -> m Profile

Get profile information.

lxcProfileConfig :: HasClient m => ProfileName -> ProfileConfigRequest -> m ()

Configure a profile.

lxcProfileDelete :: HasClient m => ProfileName -> m ()

Delete a profile

Storage

lxcStorageList :: HasClient m => m [PoolName]

List all storage pools

lxcStorageCreate :: HasClient m => PoolCreateRequest -> m ()

Create a storage pool.

lxcStorageInfo :: HasClient m => PoolName -> m Pool

Get storage pool information.

lxcStorageConfig :: HasClient m => PoolName -> PoolConfigRequest -> m ()

Configure a storage pool.

lxcStorageDelete :: HasClient m => PoolName -> m ()

Delete a storage pool

Volume

lxcVolumeList :: HasClient m => PoolName -> m [VolumeName]

List all volumes

lxcVolumeCreate :: HasClient m => PoolName -> VolumeCreateRequest -> m ()

Create a volume.

lxcVolumeInfo :: HasClient m => PoolName -> VolumeName -> m Volume

Get volume information.

lxcVolumeConfig :: HasClient m => PoolName -> VolumeName -> VolumeConfigRequest -> m ()

Configure a volume.

lxcVolumeDelete :: HasClient m => PoolName -> VolumeName -> m ()

Delete a volume