Preface

This document describes the functionality provided by the File Plugin.

Refer to the Deployit Reference Manual for background information on Deployit and deployment concepts.

Overview

In many cases, an application depends on external resources for its configuration. The application accesses these resources from a predefined location or using a predefined mechanism. In the simplest of forms, a resource can be described as a file, an archive or a folder (collection of files). The File Plugin enables the definition of such resources in a deployment package and subsequently managing them on a target host. The resources can contain placeholders that the plugin will replace when targeting to the specific host, thus allowing resources to be defined independent of their environment.

Features

Requirements

This plugin requires:

  • Deployit: version 3.5+

Usage in Deployment Packages

Please refer to Packaging Manual for more details about the DAR packaging format.

Sample DAR MANIFEST.MF entries defining a file, folder and archive resource

Manifest-Version: 1.0
Deployit-Package-Format-Version: 1.3
CI-Application: FilePluginSample
CI-Version: 1.0

Name: sampleFile.txt
CI-Name: sampleFile
CI-Type: file.File

Name: sampleArchive.zip
CI-Name: sampleArchive
CI-Type: file.Archive

Name: sampleFolder
CI-Name: sampleFolder
CI-Type: file.Folder

Using the deployables and deployeds

Deployable vs. Container Table

The following table describes which deployable / container combinations are possible. Note that the CIs can only be targeted to containers derived from Host.

Deployables Containers Generated Deployed
file.File
file.Archive		 overthere.Host file.DeployedFile
file.DeployedArchive
file.Folder overthere.Host file.DeployedFolder

Deployed Actions Table

The following table describes the effect a deployed has on its container.

DeployedCreate Destroy Modify
file.DeployedFile
file.DeployedArchive
  • Create target path on host, if needed
  • Copy file to target path on host
  • Delete file from host
  • Delete old file from host
  • Copy modified file to target path on host
file.DeployedFolder
  • Create target folder on host, if needed
  • Copy folder content to target folder on host
  • Delete folder content from host
  • If folder is not a shared folder, the folder itself is deleted from host
  • Perform actions as described by Destroy for old folder
  • Perform actions as described by Create for modified folder

CI Reference

Configuration Item Overview

Deployable Configuration Items

CIDescription
file.ArchiveAn archive (zip, jar, tar, etc) artifact that can be packaged in a Deployment Package
file.FileA single file artifact that can be packaged in a Deployment Package
file.FolderA folder artifact that can be packaged in a Deployment Package

Deployed Configuration Items

CIDescription
file.DeployedArchiveThe archive as deployed on the Host
file.DeployedFileThe file as deployed on the Host
file.DeployedFolderThe folder as deployed on the Host

Topology Configuration Items

CIDescription
overthere.CifsHostMachine that can be connected to using either WinRM or Telnet and can perform file manipulation via the CIFS protocol
overthere.LocalHostMachine on which the Deployit Server is running
overthere.SshHostMachine that can be connected to using SSH
overthere.SshJumpstationMachine that can be used to create a tunneled connection to a destination host

Virtual Deployed Configuration Items

CIDescription
file.DeployedArtifactOnHostAbstract deployed that can target any DeployableArtifact to a Host

Virtual Topology Configuration Items

CIDescription
overthere.HostMachine that runs middleware, on which scripts can be executed, etc
overthere.JumpstationBase class for jumpstations

Configuration Item Details

file.Archive

Hierarchyudm.BaseDeployableArchiveArtifact >> udm.BaseDeployableFileArtifact >> udm.BaseDeployableArtifact >> udm.BaseDeployable >> udm.BaseConfigurationItem
Interfacesudm.Taggable, udm.Deployable, udm.SourceArtifact, udm.ArchiveArtifact, udm.Artifact, udm.DeployableArtifact, udm.ConfigurationItem, udm.FileArtifact

An archive (zip, jar, tar, etc) artifact that can be packaged in a Deployment Package

Public Properties
createTargetPath : STRING

Create the targetPath on the host if it does not exist.
excludeFileNamesRegex : STRING

Regular expression that matches file names that must be excluded from scanning
placeholders : SET_OF_STRING

Placeholders detected in this artifact
scanPlaceholders : BOOLEAN = true

Scan Placeholders
tags : SET_OF_STRING

If set, this deployable will only be mapped automatically to containers with the same tag.
targetFileName : STRING

Name of the artifact on the host.
targetPath : STRING

Path to which artifact must be copied to when being deployed.
targetPathShared : STRING

Is the targetPath shared by others on the host. When true, the targetPath is not deleted during undeployment; only the artifacts copied to it.
Hidden Properties
textFileNamesRegex  : STRING = .+\.(cfg | conf | config | ini | properties | props | txt | asp | aspx | htm | html | jsf | jsp | xht | xhtml | sql | xml | xsd | xsl | xslt)

Regular expression that matches file names of text files

file.DeployedArchive

Hierarchyfile.DeployedArtifactOnHost >> udm.BaseDeployedArtifact >> udm.BaseDeployed >> udm.BaseConfigurationItem
Interfacesudm.Artifact, udm.Deployed, udm.ConfigurationItem, udm.DerivedArtifact

The archive as deployed on the Host.

Public Properties
container  : CI<udm.Container>

The container on which this deployed runs.
targetPath  : STRING

Path to which artifact must be copied to on the host.
createTargetPath : BOOLEAN = false

Create the targetPath on the host if it does not exist.
deployable : CI<udm.Deployable>

The deployable that this deployed is derived from.
placeholders : MAP_STRING_STRING

A Map containing all the placeholders mapped to their values. Special values are <ignore> or <empty>
targetFileName : STRING

Name of the artifact on the host.
targetPathShared : BOOLEAN = true

Is the targetPath shared by others on the host. When true, the targetPath is not deleted during undeployment; only the artifacts copied to it.

file.DeployedArtifactOnHost

Hierarchyudm.BaseDeployedArtifact >> udm.BaseDeployed >> udm.BaseConfigurationItem
Interfacesudm.Artifact, udm.Deployed, udm.ConfigurationItem, udm.DerivedArtifact

Abstract deployed that can target any DeployableArtifact to a Host.

Public Properties
container  : CI<udm.Container>

The container on which this deployed runs.
targetPath  : STRING

Path to which artifact must be copied to on the host.
createTargetPath : BOOLEAN = false

Create the targetPath on the host if it does not exist.
deployable : CI<udm.Deployable>

The deployable that this deployed is derived from.
placeholders : MAP_STRING_STRING

A Map containing all the placeholders mapped to their values. Special values are <ignore> or <empty>
targetFileName : STRING

Name of the artifact on the host.
targetPathShared : BOOLEAN = true

Is the targetPath shared by others on the host. When true, the targetPath is not deleted during undeployment; only the artifacts copied to it.

file.DeployedFile

Hierarchyfile.DeployedArtifactOnHost >> udm.BaseDeployedArtifact >> udm.BaseDeployed >> udm.BaseConfigurationItem
Interfacesudm.Artifact, udm.Deployed, udm.ConfigurationItem, udm.DerivedArtifact

The file as deployed on the Host.

Public Properties
container  : CI<udm.Container>

The container on which this deployed runs.
targetPath  : STRING

Path to which artifact must be copied to on the host.
createTargetPath : BOOLEAN = false

Create the targetPath on the host if it does not exist.
deployable : CI<udm.Deployable>

The deployable that this deployed is derived from.
placeholders : MAP_STRING_STRING

A Map containing all the placeholders mapped to their values. Special values are <ignore> or <empty>
targetFileName : STRING

Name of the artifact on the host.
targetPathShared : BOOLEAN = true

Is the targetPath shared by others on the host. When true, the targetPath is not deleted during undeployment; only the artifacts copied to it.

file.DeployedFolder

Hierarchyfile.DeployedArtifactOnHost >> udm.BaseDeployedArtifact >> udm.BaseDeployed >> udm.BaseConfigurationItem
Interfacesudm.Artifact, udm.Deployed, udm.ConfigurationItem, udm.DerivedArtifact

The folder as deployed on the Host.

Public Properties
container  : CI<udm.Container>

The container on which this deployed runs.
targetPath  : STRING

Path to which artifact must be copied to on the host.
createTargetPath : BOOLEAN = false

Create the targetPath on the host if it does not exist.
deployable : CI<udm.Deployable>

The deployable that this deployed is derived from.
placeholders : MAP_STRING_STRING

A Map containing all the placeholders mapped to their values. Special values are <ignore> or <empty>
targetPathShared : BOOLEAN = true

Is the targetPath shared by others on the host. When true, the targetPath is not deleted during undeployment; only the artifacts copied to it.
Hidden Properties
targetFileName : STRING

Not applicable for this type.

file.File

Hierarchyudm.BaseDeployableFileArtifact >> udm.BaseDeployableArtifact >> udm.BaseDeployable >> udm.BaseConfigurationItem
Interfacesudm.Taggable, udm.Deployable, udm.SourceArtifact, udm.Artifact, udm.DeployableArtifact, udm.ConfigurationItem, udm.FileArtifact

A single file artifact that can be packaged in a Deployment Package

Public Properties
createTargetPath : STRING

Create the targetPath on the host if it does not exist.
excludeFileNamesRegex : STRING

Regular expression that matches file names that must be excluded from scanning
placeholders : SET_OF_STRING

Placeholders detected in this artifact
scanPlaceholders : BOOLEAN = true

Scan Placeholders
tags : SET_OF_STRING

If set, this deployable will only be mapped automatically to containers with the same tag.
targetFileName : STRING

Name of the artifact on the host.
targetPath : STRING

Path to which artifact must be copied to when being deployed.
targetPathShared : STRING

Is the targetPath shared by others on the host. When true, the targetPath is not deleted during undeployment; only the artifacts copied to it.
Hidden Properties
textFileNamesRegex  : STRING = .+\.(cfg | conf | config | ini | properties | props | txt | asp | aspx | htm | html | jsf | jsp | xht | xhtml | sql | xml | xsd | xsl | xslt)

Regular expression that matches file names of text files

file.Folder

Hierarchyudm.BaseDeployableFolderArtifact >> udm.BaseDeployableArtifact >> udm.BaseDeployable >> udm.BaseConfigurationItem
Interfacesudm.Taggable, udm.Deployable, udm.SourceArtifact, udm.Artifact, udm.DeployableArtifact, udm.ConfigurationItem, udm.FolderArtifact

A folder artifact that can be packaged in a Deployment Package

Public Properties
createTargetPath : STRING

Create the targetPath on the host if it does not exist.
excludeFileNamesRegex : STRING

Regular expression that matches file names that must be excluded from scanning
placeholders : SET_OF_STRING

Placeholders detected in this artifact
scanPlaceholders : BOOLEAN = true

Scan Placeholders
tags : SET_OF_STRING

If set, this deployable will only be mapped automatically to containers with the same tag.
targetFileName : STRING

Name of the artifact on the host.
targetPath : STRING

Path to which artifact must be copied to when being deployed.
targetPathShared : STRING

Is the targetPath shared by others on the host. When true, the targetPath is not deleted during undeployment; only the artifacts copied to it.
Hidden Properties
textFileNamesRegex  : STRING = .+\.(cfg | conf | config | ini | properties | props | txt | asp | aspx | htm | html | jsf | jsp | xht | xhtml | sql | xml | xsd | xsl | xslt)

Regular expression that matches file names of text files

overthere.CifsHost

Hierarchyoverthere.Host >> udm.BaseContainer >> udm.BaseConfigurationItem
Interfacesudm.Taggable, udm.ConfigurationItem, udm.Container, overthere.HostContainer

Machine that can be connected to using either WinRM or Telnet and can perform file manipulation via the CIFS protocol

Public Properties
address  : STRING

Address of the host
connectionType  : ENUM [TELNET, WINRM, WINRM_HTTP, WINRM_HTTPS] = WINRM

Connection Type
os  : ENUM [WINDOWS, UNIX]

Operating system
password  : STRING

Password to use for authentication
username  : STRING

Username to connect with
cifsPort : INTEGER = 445

Port on which the CIFS server runs
deploymentGroup : INTEGER

If the group-orchestrator is enabled, all containers with the same deployment group number will be deployed to at the same time. The groups are ordered by this number.
jumpstation : CI<overthere.Jumpstation>

Jumpstation that should be used to reach this host
pathShareMappings : MAP_STRING_STRING

Mapping from Windows paths to Windows share names, e.g. C:\IBM\WebSphere -> WebSphereShare
port : INTEGER

Port on which the Telnet or WinRM server runs
tags : SET_OF_STRING

If set, only deployables with the same tag will be automatically mapped to this container.
temporaryDirectoryPath : STRING

Directory into which temporary files are stored. Will be cleaned up when the connection is closed.
winrmEnableHttps : BOOLEAN = false

Enable SSL communication to the WinRM server
Hidden Properties
connectionTimeoutMillis  : INTEGER = 1200000

Number of milliseconds Overthere waits for a connection to a remote host to be established
protocol  : STRING = cifs

Protocol
tmpFileCreationRetries  : INTEGER = 1000

Number of times Overthere attempts to create a temporary file with a unique name
winrmContext  : STRING = /wsman

Context used by the WinRM server
winrmEnvelopSize  : INTEGER = 153600

Envelop size for WinRM messages
winrmHttpsCertificateTrustStrategy  : ENUM [STRICT, SELF_SIGNED, ALLOW_ALL] = STRICT

HTTPS certifiacte trust strategy for WinRM over HTTPS
winrmHttpsHostnameVerificationStrategy  : ENUM [STRICT, BROWSER_COMPATIBLE, ALLOW_ALL] = STRICT

HTTPS host name verification strategy for WinRM over HTTPS
winrmLocale  : STRING = en-US

Locale to use for WinRM messages
winrmTimeout  : STRING = PT60.000S

Timeout to use for WinRM messages in XML schema duration format
tmpDeleteOnDisconnect : BOOLEAN = true

Whether to delete the temporary connection directory when the connection is closed
winrmDebugKerberosAuth : BOOLEAN = false

If true, enabled Kerberos debug messages
Control Tasks
checkConnection

Check connection

overthere.Host

Hierarchyudm.BaseContainer >> udm.BaseConfigurationItem
Interfacesudm.Taggable, udm.ConfigurationItem, udm.Container, overthere.HostContainer

Machine that runs middleware, on which scripts can be executed, etc.

Public Properties
os  : ENUM [WINDOWS, UNIX]

Operating system
deploymentGroup : INTEGER

If the group-orchestrator is enabled, all containers with the same deployment group number will be deployed to at the same time. The groups are ordered by this number.
jumpstation : CI<overthere.Jumpstation>

Jumpstation that should be used to reach this host
tags : SET_OF_STRING

If set, only deployables with the same tag will be automatically mapped to this container.
temporaryDirectoryPath : STRING

Directory into which temporary files are stored. Will be cleaned up when the connection is closed.
Hidden Properties
connectionTimeoutMillis  : INTEGER = 1200000

Number of milliseconds Overthere waits for a connection to a remote host to be established
protocol  : STRING

Protocol to use when connecting to this host
tmpFileCreationRetries  : INTEGER = 1000

Number of times Overthere attempts to create a temporary file with a unique name
tmpDeleteOnDisconnect : BOOLEAN = true

Whether to delete the temporary connection directory when the connection is closed
Control Tasks
checkConnection

Check connection

overthere.Jumpstation

Hierarchyoverthere.Host >> udm.BaseContainer >> udm.BaseConfigurationItem
Interfacesudm.Taggable, udm.ConfigurationItem, udm.Container, overthere.HostContainer

Base class for jumpstations

Public Properties
deploymentGroup : INTEGER

If the group-orchestrator is enabled, all containers with the same deployment group number will be deployed to at the same time. The groups are ordered by this number.
jumpstation : CI<overthere.Jumpstation>

Jumpstation that should be used to reach this host
tags : SET_OF_STRING

If set, only deployables with the same tag will be automatically mapped to this container.
Hidden Properties
connectionTimeoutMillis  : INTEGER = 1200000

Number of milliseconds Overthere waits for a connection to a remote host to be established
os  : ENUM [WINDOWS, UNIX] = UNIX

Os
protocol  : STRING

Protocol to use when connecting to this host
tmpFileCreationRetries  : INTEGER = 1000

Number of times Overthere attempts to create a temporary file with a unique name
temporaryDirectoryPath : STRING

The default platform value (/tmp) suffices as no temporary files will be placed on the jumpstation
tmpDeleteOnDisconnect : BOOLEAN = true

Whether to delete the temporary connection directory when the connection is closed
Control Tasks
checkConnection

Check connection

overthere.LocalHost

Hierarchyoverthere.Host >> udm.BaseContainer >> udm.BaseConfigurationItem
Interfacesudm.Taggable, udm.ConfigurationItem, udm.Container, overthere.HostContainer

Machine on which the Deployit Server is running

Public Properties
os  : ENUM [WINDOWS, UNIX]

Operating system
deploymentGroup : INTEGER

If the group-orchestrator is enabled, all containers with the same deployment group number will be deployed to at the same time. The groups are ordered by this number.
jumpstation : CI<overthere.Jumpstation>

Jumpstation that should be used to reach this host
tags : SET_OF_STRING

If set, only deployables with the same tag will be automatically mapped to this container.
temporaryDirectoryPath : STRING

Directory into which temporary files are stored. Will be cleaned up when the connection is closed.
Hidden Properties
connectionTimeoutMillis  : INTEGER = 1200000

Number of milliseconds Overthere waits for a connection to a remote host to be established
protocol  : STRING = local

Protocol
tmpFileCreationRetries  : INTEGER = 1000

Number of times Overthere attempts to create a temporary file with a unique name
tmpDeleteOnDisconnect : BOOLEAN = true

Whether to delete the temporary connection directory when the connection is closed
Control Tasks
checkConnection

Check connection

overthere.SshHost

Hierarchyoverthere.Host >> udm.BaseContainer >> udm.BaseConfigurationItem
Interfacesudm.Taggable, udm.ConfigurationItem, udm.Container, overthere.HostContainer

Machine that can be connected to using SSH

Public Properties
address  : STRING

Address of the host
connectionType  : ENUM [SFTP, SFTP_CYGWIN, SFTP_WINSSHD, SCP, SUDO, INTERACTIVE_SUDO, TUNNEL] = SFTP

Type of SSH connection to create
os  : ENUM [WINDOWS, UNIX]

Operating system
port  : INTEGER = 22

Port on which the SSH server runs
username  : STRING

Username to connect with
deploymentGroup : INTEGER

If the group-orchestrator is enabled, all containers with the same deployment group number will be deployed to at the same time. The groups are ordered by this number.
jumpstation : CI<overthere.Jumpstation>

Jumpstation that should be used to reach this host
passphrase : STRING

Optional passphrase for the private key in the private key file
password : STRING

Password to use for authentication
privateKeyFile : STRING

Private key file to use for authentication
sudoUsername : STRING

Username to sudo to when accessing files or executing commands
tags : SET_OF_STRING

If set, only deployables with the same tag will be automatically mapped to this container.
temporaryDirectoryPath : STRING

Directory into which temporary files are stored. Will be cleaned up when the connection is closed.
Hidden Properties
connectionTimeoutMillis  : INTEGER = 1200000

Number of milliseconds Overthere waits for a connection to a remote host to be established
interactiveKeyboardAuthRegex  : STRING = .*Password:[ ]?

Regular expression to look for in keyboard-interactive authentication before sending the password
protocol  : STRING = ssh

Protocol
sudoCommandPrefix  : STRING = sudo -u {0}

Sudo command to prefix to the original command. The placeholder {0} is replaced with the sudoUsername
sudoPasswordPromptRegex  : STRING = .*[Pp]assword.*:

Regular expression to look for in interactive sudo before sending the password
tmpFileCreationRetries  : INTEGER = 1000

Number of times Overthere attempts to create a temporary file with a unique name
allocateDefaultPty : BOOLEAN = false

If true, a default PTY (dummy:80:24:0:0) is allocated when executing a command
allocatePty : STRING

Specification for the PTY to be allocated when executing a command. The format is TERM:COLS:ROWS:WIDTH:HEIGHT, e.g. xterm:80:24:0:0
sudoOverrideUmask : BOOLEAN = true

If true, permissions are explicitly changed with chmod -R go+rX after uploading a file or directory
sudoPreserveAttributesOnCopyFromTempFile : BOOLEAN = true

If true, files are copied from the connection temporary directory using the -p flag to the cp command
sudoPreserveAttributesOnCopyToTempFile : BOOLEAN = true

If true, files are copied to the connection temporary directory using the -p flag to the cp command
sudoQuoteCommand : BOOLEAN = false

If true, the original command is quoted when it is prefixed with sudoCommandPrefix
tmpDeleteOnDisconnect : BOOLEAN = true

Whether to delete the temporary connection directory when the connection is closed
Control Tasks
checkConnection

Check connection

overthere.SshJumpstation

Hierarchyoverthere.Jumpstation >> overthere.Host >> udm.BaseContainer >> udm.BaseConfigurationItem
Interfacesudm.Taggable, udm.ConfigurationItem, udm.Container, overthere.HostContainer

Machine that can be used to create a tunneled connection to a destination host

Public Properties
address  : STRING

Address of the host
port  : INTEGER = 22

Port on which the SSH server runs
username  : STRING

Username to connect with
deploymentGroup : INTEGER

If the group-orchestrator is enabled, all containers with the same deployment group number will be deployed to at the same time. The groups are ordered by this number.
jumpstation : CI<overthere.Jumpstation>

Jumpstation that should be used to reach this host
passphrase : STRING

Optional passphrase for the private key in the private key file
password : STRING

Password to use for authentication
privateKeyFile : STRING

Private key file to use for authentication
tags : SET_OF_STRING

If set, only deployables with the same tag will be automatically mapped to this container.
Hidden Properties
connectionTimeoutMillis  : INTEGER = 1200000

Number of milliseconds Overthere waits for a connection to a remote host to be established
connectionType  : ENUM [SFTP, SFTP_CYGWIN, SFTP_WINSSHD, SCP, SUDO, INTERACTIVE_SUDO, TUNNEL] = TUNNEL

Connection Type
interactiveKeyboardAuthRegex  : STRING = .*Password:[ ]?

Regular expression to look for in keyboard-interactive authentication before sending the password
os  : ENUM [WINDOWS, UNIX] = UNIX

Os
portAllocationRangeStart  : INTEGER = 1025

Port from where to start looking for freely available ports to use as the local part of an SSH port forward
protocol  : STRING = ssh

Protocol
tmpFileCreationRetries  : INTEGER = 1000

Number of times Overthere attempts to create a temporary file with a unique name
temporaryDirectoryPath : STRING

The default platform value (/tmp) suffices as no temporary files will be placed on the jumpstation
tmpDeleteOnDisconnect : BOOLEAN = true

Whether to delete the temporary connection directory when the connection is closed
Control Tasks
checkConnection

Check connection
Copyright XebiaLabs B.V. 2009-2012. All rights reserved.