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.CifsHostA machine that can be connected to using either WinRM or Telnet and can perform file manipulation via the CIFS protocol
overthere.LocalHostThe machine on which the Deployit Server is running on
overthere.SshHostA machine that can be connected to using ssh
overthere.SshJumpstationA machine that can be used to create a tunneled connection to the destination host

Virtual Deployed Configuration Items

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

Virtual Topology Configuration Items

CIDescription
overthere.HostA machine 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

The tags to map deployables to containers.
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

The tags to map deployables to containers.
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

The tags to map deployables to containers.
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

A 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_HTTP, WINRM_HTTPS] = TELNET

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

The deployment group of this container.
jumpstation : CI<overthere.Jumpstation>

If this host is not directly reachable, specify a jumpstation here which can be used to reach this host.
port : INTEGER

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

The tags to map deployables to containers.
temporaryDirectoryPath : STRING

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

Connection Timeout Millis
protocol  : STRING = cifs

Protocol
tmpFileCreationRetries  : INTEGER = 1000

Tmp File Creation Retries
winrmContext  : STRING = /wsman

Winrm Context
winrmEnvelopSize  : INTEGER = 153600

Winrm Envelop Size
winrmLocale  : STRING = en-US

Winrm Locale
winrmTimeout  : STRING = PT60.000S

Winrm Timeout
tmpDeleteOnDisconnect : BOOLEAN = true

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

Check connection

overthere.Host

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

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

Public Properties
os  : ENUM [WINDOWS, UNIX]

Operating system
deploymentGroup : INTEGER

The deployment group of this container.
jumpstation : CI<overthere.Jumpstation>

If this host is not directly reachable, specify a jumpstation here which can be used to reach this host.
tags : SET_OF_STRING

The tags to map deployables to containers.
temporaryDirectoryPath : STRING

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

Connection Timeout Millis
protocol  : STRING

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

Tmp File Creation Retries
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

The deployment group of this container.
jumpstation : CI<overthere.Jumpstation>

If this host is not directly reachable, specify a jumpstation here which can be used to reach this host.
tags : SET_OF_STRING

The tags to map deployables to containers.
Hidden Properties
connectionTimeoutMillis  : INTEGER = 1200000

Connection Timeout Millis
os  : ENUM [WINDOWS, UNIX] = UNIX

Os
protocol  : STRING

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

Tmp File Creation Retries
temporaryDirectoryPath : STRING

Temporary Directory Path
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

The machine on which the Deployit Server is running on.

Public Properties
os  : ENUM [WINDOWS, UNIX]

Operating system
deploymentGroup : INTEGER

The deployment group of this container.
jumpstation : CI<overthere.Jumpstation>

If this host is not directly reachable, specify a jumpstation here which can be used to reach this host.
tags : SET_OF_STRING

The tags to map deployables to containers.
temporaryDirectoryPath : STRING

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

Connection Timeout Millis
protocol  : STRING = local

Protocol
tmpFileCreationRetries  : INTEGER = 1000

Tmp File Creation Retries
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

A 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

The deployment group of this container.
jumpstation : CI<overthere.Jumpstation>

If this host is not directly reachable, specify a jumpstation here which can 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

The tags to map deployables to containers.
temporaryDirectoryPath : STRING

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

Connection Timeout Millis
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

Tmp File Creation Retries
allocateDefaultPty : BOOLEAN = false

If true, a default pty is allocated when executing a command. All sudo implementations require it for interactive sudo, some even require it for normal sudo. Some SSH server implementations (notably the one on AIX 5.3) crash when it is allocated.
sudoOverrideUmask : BOOLEAN = false

If true, permissions are explicitly changed with chmod -R go+rX after uploading a file or directory with scp.
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

A machine that can be used to create a tunneled connection to the 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

The deployment group of this container.
jumpstation : CI<overthere.Jumpstation>

If this host is not directly reachable, specify a jumpstation here which can 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

The tags to map deployables to containers.
Hidden Properties
connectionTimeoutMillis  : INTEGER = 1200000

Connection Timeout Millis
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
protocol  : STRING = ssh

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

Tmp File Creation Retries
temporaryDirectoryPath : STRING

Temporary Directory Path
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.