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

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

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

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

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

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

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

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

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