pallet.actions — dda/pallet 0.9.1

Pallet's action primitives.

add-rpm clj

(add-rpm rpm-name & {:as options})

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

all-options clj

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

as-action clj macro

(as-action & body)

Wrap arbitrary clojure code to be run as an action

assoc-in-settings clj

(assoc-in-settings 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 clj

(assoc-settings 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).

check-remote-directory-arguments clj macro

(check-remote-directory-arguments m)

check-remote-file-arguments clj macro

(check-remote-file-arguments m)

content-options clj

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 clj

(debconf-set-selections {:keys [line package question type value]})

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

delete-local-path clj

(delete-local-path local-path)

Function to delete a local path.

directories clj

(directories 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 clj

(directory 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 clj

(exec {: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 clj macro

(exec-checked-script script-name & script)

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

exec-script clj macro

(exec-script & script)

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

exec-script* clj

(exec-script* script)

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

fifo clj

(fifo 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 clj

(file 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 clj

(group 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 clj

(install-deb deb-name & {:as options})

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

log-script-output clj macro

(log-script-output 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 clj

(minimal-packages)

Add minimal packages for pallet to function

on-one-node clj macro

(on-one-node 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.

one-node-filter clj

(one-node-filter role->nodes [role & roles])

ownership-options clj

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

package clj

(package 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 clj

(package-manager 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 clj

(package-source 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"]})

package-source-changed-flag clj

packages clj

(packages & {: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 clj

(plan-flag-kw)

Generator for plan flag keywords

plan-when clj macro

(plan-when condition & crate-fns-or-actions)

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

plan-when-not clj macro

(plan-when-not condition & crate-fns-or-actions)

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

remote-directory clj

(remote-directory 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 blob blobstore]
                   :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

:no-versioning : flag to not apply versioning to downloaded archives

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-directory-arguments clj

remote-file clj

(remote-file 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-arguments clj

remote-file-content clj

(remote-file-content path)

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

repository clj multimethod

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

retry-until clj macro

(retry-until {:keys [max-retries standoff service-name]
              :or {max-retries 5 standoff 2}}
             condition)

Repeat an action until it succeeds

return-value-expr clj macro deprecated

(return-value-expr [& return-values] & body)

Creates an action that can transform return values

rsync clj

(rsync local-path remote-path {:keys [port]})

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

rsync-directory clj

(rsync-directory from to & {:keys [owner group mode port] :as options})

Rsync from a local directory to a remote directory.

rsync-to-local clj

(rsync-to-local remote-path local-path {:keys [port]})

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

rsync-to-local-directory clj

(rsync-to-local-directory from to & {:keys [owner group mode port] :as options})

Rsync from a local directory to a remote directory.

sed clj

(sed 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 clj

(service 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 clj

(service-script 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 clj

(set-force-overwrite flag)

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

set-install-new-files clj

(set-install-new-files flag)

Set boolean flag to control installation of new files

setup-node clj

(setup-node)

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

symbolic-link clj

(symbolic-link 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 clj

(transfer-file 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 clj

(transfer-file-to-local remote-path local-path)

Function to transfer a remote file to a local path.

update-settings clj

(update-settings 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 clj

(user 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 clj

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

wait-for-file clj

(wait-for-file 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 clj macro

(with-action-values [& return-values] & body)

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

with-remote-file clj

(with-remote-file 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 clj macro

(with-service-restart service-name & body)

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