pallet.actions documentation

Pallet's action primitives.

add-rpm

fn

[rpm-name & {:as options}]

Add an rpm. Source options are as for remote file.

all-options

var

A vector of the options accepted by remote-file. Can be used for option forwarding when calling remote-file from other crates.

as-action

macro

[& body]

Wrap arbitrary clojure code to be run as an action

assoc-in-settings

fn

[path value & {:keys [instance-id]}]

Put the specified value (possible a NodeValue) into the settings for path, a vector of [facility & keys], specifying a facility an a path.

assoc-settings

fn

[facility kv-pairs & {:keys [instance-id]}]

Set the settings for the specified host facility. The instance-id allows the specification of specific instance of the facility (the default is :default).

content-options

var

A vector of the options accepted by remote-file. Can be used for option forwarding when calling remote-file from other crates.

debconf-set-selections

fn

[{:keys [line package question type value]}]

Set debconf selections. Specify :line as a string, or :package, :question, :type and :value options.

delete-local-path

fn

[local-path]

Function to delete a local path.

directories

fn

[paths & options]

Directory management of multiple directories with the same owner/group/permissions.

options are as for directory and are applied to each directory in paths

directory

fn

[dir-path & {:keys [action recursive force path mode verbose owner group], :or {action :create, recursive true, force true, path true}}]

Directory management.

For :create and :touch, all components of path are effected.

Options are: - :action One of :create, :touch, :delete - :recursive Flag for recursive delete - :force Flag for forced delete - :path flag to create all path elements - :owner set owner - :group set group - :mode set mode

exec

fn

[{:keys [language interpreter version], :or {language :bash}} script]

Execute script on the target node. The script is a plain string. type specifies the script language (default :bash). You can override the interpreter path using the :interpreter option.

exec-checked-script

macro

[script-name & script]

Execute a bash script remotely, throwing if any element of the script fails. The script is expressed in stevedore.

exec-script

macro

[& script]

Execute a bash script remotely. The script is expressed in stevedore.

exec-script*

fn

[script]

Execute script on the target node. The script is a plain string.

fifo

fn

[path & {:keys [action owner group mode force], :or {action :create}}]

FIFO pipe management.

  • :action one of :create, :delete
  • :owner user name or id for owner of fifo
  • :group user name or id for group of fifo
  • :mode fifo permissions
  • :force when deleting, try and force removal

file

fn

[path & {:keys [action owner group mode force], :or {action :create, force true}}]

Touch or remove a file. Can also set owner and permissions.

  • :action one of :create, :delete, :touch
  • :owner user name or id for owner of file
  • :group user name or id for group of file
  • :mode file permissions
  • :force when deleting, try and force removal

group

fn

[groupname & {:keys [action system gid password], :or {action :manage}, :as options}]

User Group Management.

:action : One of :create, :manage, :remove.

:gid : specify the group id

:password : An MD5 crypted password for the user.

:system : Specify the user as a system user.

install-deb

fn

[deb-name & {:as options}]

Add a deb. Source options are as for remote file.

log-script-output

macro

[script-return-value {:keys [out err exit fmt], :or {out :debug, err :info, exit :none, fmt "%s"}}]

Log the result of a script action.

minimal-packages

fn

[]

Add minimal packages for pallet to function

on-one-node

macro

[roles & body]

Execute the body on just one node of the specified roles. If there is no node in the union of nodes for all the roles, the nodes for the first role are used.

ownership-options

var

A vector of options for controlling ownership. Can be used for option forwarding when calling remote-file from other crates.

package

fn

[package-name & {:keys [action y force purge enable disable priority], :or {action :install, y true, priority 50}}]

Install or remove a package.

Options - :action [:install | :remove | :upgrade] - :purge [true|false] when removing, whether to remove all config - :enable [repo|(seq repo)] enable specific repository - :disable [repo|(seq repo)] disable specific repository - :priority n priority (0-100, default 50) - :disable-service-start disable service startup (default false) - :allow-unsigned install package even if unsigned

Package management occurs in one shot, so that the package manager can maintain a consistent view.

package-manager

fn

[action & options]

Package manager controls.

action is one of the following: - :update - update the list of available packages - :list-installed - output a list of the installed packages - :add-scope - enable a scope (eg. multiverse, non-free)

To refresh the list of packages known to the package manager: (package-manager session :update)

To enable multiverse on ubuntu: (package-manager session :add-scope :scope :multiverse)

To enable non-free on debian: (package-manager session :add-scope :scope :non-free)

package-source

fn

[name & {:keys [aptitude yum]}]

Control package sources. Options are the package manager keywords, each specifying a map of packager specific options.

`:aptitude`

:source-type source-string : the source type (default "deb")

:url url-string : the repository url

:scopes seq : scopes to enable for repository

:release release-name : override the release name

:key-url url-string : url for key

:key-server hostname : hostname to use as a keyserver

:key-id id : id for key to look it up from keyserver

`:yum`

:name name : repository name

:url url-string : repository base url

:gpgkey url-string : gpg key url for repository

Example

(package-source "Partner"
  :aptitude {:url "http://archive.canonical.com/"
             :scopes ["partner"]})

packages

fn

[& {:keys [yum aptitude pacman brew], :as options}]

Install a list of packages keyed on packager. (packages session :yum ["git" "git-email"] :aptitude ["git-core" "git-email"])

plan-flag-kw

fn

[]

Generator for plan flag keywords

plan-when

macro

[condition & crate-fns-or-actions]

Execute the crate-fns-or-actions, only when condition is true.

plan-when-not

macro

[condition & crate-fns-or-actions]

Execute the crate-fns-or-actions, only when condition is false.

remote-directory

fn

[path & {:keys [action url local-file remote-file unpack tar-options unzip-options jar-options strip-components md5 md5-url owner group recursive force-overwrite local-file-options], :or {action :create, tar-options "xz", unzip-options "-o", jar-options "xf", strip-components 1, recursive true}, :as options}]

Specify the contents of remote directory.

Options:

:url : a url to download content from

:unpack : how download should be extracts (default :tar)

:tar-options : options to pass to tar (default "xz")

:unzip-options : options to pass to unzip (default "-o")

:jar-options : options to pass to unzip (default "xf") jar does not support stripping path components

:strip-components : number of path components to remove when unpacking

:extract-files : extract only the specified files or directories from the archive

:md5 : md5 of file to unpack

:md5-url : url of md5 file for file to unpack

Ownership options: :owner : owner of files

:group : group of files

:recursive : flag to recursively set owner and group

To install the content of an url pointing at a tar file, specify the :url option.

(remote-directory session path
   :url "http://a.com/path/file.tgz")

If there is an md5 url with the tar file's md5, you can specify that as well, to prevent unnecessary downloads and verify the content.

(remote-directory session path
   :url "http://a.com/path/file.tgz"
   :md5-url "http://a.com/path/file.md5")

To install the content of an url pointing at a zip file, specify the :url option and :unpack :unzip.

(remote-directory session path
   :url "http://a.com/path/file."
   :unpack :unzip)

To install the content of an url pointing at a jar/tar/zip file, extracting only specified files or directories, use the :extract-files option.

(remote-directory session path
   :url "http://a.com/path/file.jar"
   :unpack :jar
   :extract-files ["dir/file" "file2"])

remote-file

fn

[path & {:keys [action url local-file remote-file link content literal template values md5 md5-url owner group mode force blob blobstore install-new-files overwrite-changes no-versioning max-versions flag-on-changed local-file-options verify], :as options}]

Remote file content management.

The remote-file action can specify the content of a remote file in a number different ways.

By default, the remote-file is versioned, and 5 versions are kept.

The remote content is also verified against its md5 hash. If the contents of the remote file have changed (e.g. have been edited on the remote machine) then by default the file will not be overwritten, and an error will be raised. To force overwrite, call set-force-overwrite before running converge or lift.

Options for specifying the file's content are: url : download the specified url to the given filepath

content : use the specified content directly

local-file : use the file on the local machine at the given path

remote-file : use the file on the remote machine at the given path

link : file to link to

literal : prevent shell expansion on content

md5 : md5 for file

md5-url : a url containing file's md5

template : specify a template to be interpolated

values : values for interpolation

blob : map of container, path

blobstore : a jclouds blobstore object (override blobstore in session)

insecure : boolean to specify ignoring of SLL certs

Options for version control are:

overwrite-changes : flag to force overwriting of locally modified content

no-versioning : do not version the file

max-versions : specify the number of versions to keep (default 5)

flag-on-changed : flag to set if file is changed

Options for specifying the file's permissions are:

owner : user-name

group : group-name

mode : file-mode

Options for verifying the file's content:

verify : a command to run on the file on the node, before it is installed

To copy the content of a local file to a remote file: (remote-file session "remote/path" :local-file "local/path")

To copy the content of one remote file to another remote file: (remote-file session "remote/path" :remote-file "remote/source/path")

To link one remote file to another remote file: (remote-file session "remote/path" :link "remote/source/path")

To download a url to a remote file: (remote-file session "remote/path" :url "http://a.com/path")

If a url to a md5 file is also available, then it can be specified to prevent unnecessary downloads and to verify the download.

(remote-file session "remote/path"
  :url "http://a.com/path"
  :md5-url "http://a.com/path.md5")

If the md5 of the file to download, it can be specified to prevent unnecessary downloads and to verify the download.

(remote-file session "remote/path"
  :url "http://a.com/path"
  :md5 "6de9439834c9147569741d3c9c9fc010")

Content can also be copied from a blobstore.

(remote-file session "remote/path"
  :blob {:container "container" :path "blob"})

remote-file-content

fn

[path]

Return a function that returns the content of a file, when used inside another action.

repository

var

Install the specified repository as a package source. The :id key must contain a recognised repository.

retry-until

macro

[{:keys [max-retries standoff service-name], :or {max-retries 5, standoff 2}} condition]

Repeat an action until it succeeds

return-value-expr

macro

[[& return-values] & body]

Deprecated: 0.8.0-beta.8

Creates an action that can transform return values

rsync

fn

[local-path remote-path {:keys [port]}]

Use rsync to copy files from local-path to remote-path

rsync-directory

fn

[from to & {:keys [owner group mode port], :as options}]

Rsync from a local directory to a remote directory.

rsync-to-local

fn

[remote-path local-path {:keys [port]}]

Use rsync to copy files from remote-path to local-path

rsync-to-local-directory

fn

[from to & {:keys [owner group mode port], :as options}]

Rsync from a local directory to a remote directory.

sed

fn

[path exprs-map & {:keys [separator no-md5 restriction]}]

Execute sed on the file at path. Takes a map of expr to replacement. - :separator the separator to use in generated sed expressions. This will be inferred if not specified. - :no-md5 prevent md5 generation for the modified file - :restriction restrict the sed expressions to a particular context.

service

fn

[service-name & {:keys [action if-flag if-stopped service-impl], :or {action :start, service-impl :initd}, :as options}]

Control services.

  • :action accepts either startstop, restart, enable or disable keywords.
  • :if-flag makes start, stop, and restart conditional on the specified flag as set, for example, by remote-file :flag-on-changed
  • :sequence-start a sequence of [sequence-number level level ...], where sequence number determines the order in which services are started within a level.
  • :service-impl either :initd or :upstart

Deprecated in favour of pallet.crate.service/service.

service-script

fn

[service-name & {:keys [action url local-file remote-file link content literal template values md5 md5-url force service-impl], :or {action :create, service-impl :initd}, :as options}]

Install a service script. Sources as for remote-file.

set-force-overwrite

fn

[flag]

Globally force installation of new files, even if content on node has changed.

set-install-new-files

fn

[flag]

Set boolean flag to control installation of new files

setup-node

fn

[]

Action to setup the node. Use this if file transfers fail due to e.g state-root not existing.

symbolic-link

fn

[from name & {:keys [action owner group mode force], :or {action :create, force true}}]

Symbolic link management.

  • :action one of :create, :delete
  • :owner user name or id for owner of symlink
  • :group user name or id for group of symlink
  • :mode symlink permissions
  • :force when deleting, try and force removal
  • :no-deref do not deref target if it is a symlink to a directory

transfer-file

fn

[local-path remote-path]

Function to transfer a local file to a remote path. Prefer remote-file or remote-directory over direct use of this action.

transfer-file-to-local

fn

[remote-path local-path]

Function to transfer a remote file to a local path.

update-settings

fn

[facility options-or-f & args]

Update the settings for the specified host facility. The instance-id allows the specification of specific instance of the facility (the default is :default).

user

fn

[username & {:keys [action shell base-dir home system create-home password shell comment group groups remove force append], :or {action :manage}, :as options}]

User management.

:action : One of :create, :manage, :lock, :unlock or :remove.

:shell : One of :bash, :csh, :ksh, :rsh, :sh, :tcsh, :zsh, :false or a path string.

:create-home : Controls creation of the user's home directory.

:base-dir : The directory in which default user directories should be created.

:home : Specify the user's home directory.

:system : Specify the user as a system user.

:comment : A comment to record for the user.

:group : The user's login group. Defaults to a group with the same name as the user.

:groups : Additional groups the user should belong to.

:password : An MD5 crypted password for the user.

:force : Force user removal.

version-options

var

A vector of options for controlling versions. Can be used for option forwarding when calling remote-file from other crates.

wait-for-file

fn

[path & {:keys [max-retries standoff service-name], :or {action :create, max-versions 5, install-new-files true}, :as options}]

Wait for a file to exist

with-action-values

macro

[[& return-values] & body]

Creates an action that can transform action return values. The return value is itself an action return value.

with-remote-file

fn

[f path & args]

Function to call f with a local copy of the sessioned remote path. f should be a function taking [session local-path & _], where local-path will be a File with a copy of the remote file (which will be unlinked after calling f.

with-service-restart

macro

[service-name & body]

Stop the given service, execute the body, and then restart.