# 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

- Deploy, upgrade, and undeploy of a file based resource on a Host.
  - File
  - Folder
  - Archive

# 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.

Deployed | Create | 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

### Deployed Configuration Items

### Topology Configuration Items

### Virtual Deployed Configuration Items

### Virtual Topology Configuration Items

## Configuration Item Details

### file.Archive

Hierarchy | udm.BaseDeployableArchiveArtifact >> udm.BaseDeployableFileArtifact >> udm.BaseDeployableArtifact >> udm.BaseDeployable >> udm.BaseConfigurationItem
Interfaces | udm.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

Hierarchy | file.DeployedArtifactOnHost >> udm.BaseDeployedArtifact >> udm.BaseDeployed >> udm.BaseConfigurationItem
Interfaces | udm.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

Hierarchy | udm.BaseDeployedArtifact >> udm.BaseDeployed >> udm.BaseConfigurationItem
Interfaces | udm.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

Hierarchy | file.DeployedArtifactOnHost >> udm.BaseDeployedArtifact >> udm.BaseDeployed >> udm.BaseConfigurationItem
Interfaces | udm.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

Hierarchy | file.DeployedArtifactOnHost >> udm.BaseDeployedArtifact >> udm.BaseDeployed >> udm.BaseConfigurationItem
Interfaces | udm.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

Hierarchy | udm.BaseDeployableFileArtifact >> udm.BaseDeployableArtifact >> udm.BaseDeployable >> udm.BaseConfigurationItem
Interfaces | udm.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

Hierarchy | udm.BaseDeployableFolderArtifact >> udm.BaseDeployableArtifact >> udm.BaseDeployable >> udm.BaseConfigurationItem
Interfaces | udm.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

Hierarchy | overthere.Host >> udm.BaseContainer >> udm.BaseConfigurationItem
Interfaces | udm.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

Hierarchy | udm.BaseContainer >> udm.BaseConfigurationItem
Interfaces | udm.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

Hierarchy | overthere.Host >> udm.BaseContainer >> udm.BaseConfigurationItem
Interfaces | udm.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

Hierarchy | overthere.Host >> udm.BaseContainer >> udm.BaseConfigurationItem
Interfaces | udm.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

Hierarchy | overthere.Host >> udm.BaseContainer >> udm.BaseConfigurationItem
Interfaces | udm.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

Hierarchy | overthere.Jumpstation >> overthere.Host >> udm.BaseContainer >> udm.BaseConfigurationItem
Interfaces | udm.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