File-Transfer Plug-in

The File-Transfer Plug-in transfers a file or folder to or from a remote host.

If you have pre-set authentication information in the Agentless Remote Connections view, you can run the File-Transfer Plug-in by specifying the following information:

operation target device (remoteHost property)
Transfer mode (transferMode property)
Path of a file or folder on the Ops Center Automator server (localFilePath property)
Path of a file or folder on the operation target device (remoteFilePath property)

In the file path for forwarding to the agentless connection destination, specify characters that can be used in commands in the OSs of the Ops Center Automator server and the operation target device. For example, if the Ops Center Automator server and the operation target device are both running the Windows OS with Japanese Locale, characters in the MS932 character set can be specified.

If destination host is a Ops Center Automator server (localhost), the user ID and the password are unnecessary.

If the operation target device is running Windows, the file is transferred by the user set in the authentication information.

If the operation target device is running Linux OS, the file is transferred subject to the privileges of the root user or the connection user, depending on the value of the elevatePrivileges property.

Note: If the local execution function is enabled, the file is not forwarded. If the OS of the local host is Windows, the file is copied to the local host with the privileges of the System account. If the OS of the local host is Linux, the file is copied to the local host with root user privileges.

Prerequisites

Depending on the OS of the operation target device, configure the environment as follows:

For Windows

Make sure that the Ops Center Automator server and operation target device can communicate using the specified ports.
Before running the file-forwarding plug-in, enable administrative sharing on the operation target device.

For Linux OS

You can set the SSH port number in the connection-destination properties file (connection-destination-name.properties) or the properties file (config_user.properties).
On the operation target device, install an SSH server that supports SCP or SFTP.

Specific commands must be installed in the OS of the operation target device before you use the File-Transfer Plug-in.

Cautionary notes

IPv6 is not supported when Ops Center Automator is running on Linux OS and the destination host is Windows.
The execution method differs depending on the OS of the operation target device. File transfer is implemented by RPC and CIFS (SMB) in Windows, and SSH (SCP or SFTP) in Linux OS. When selecting a protocol in the definition of an agentless connection destination, select Windows in Windows and SSH in Linux OS. Note that the feature to suspend and resume file transfers using SFTP is not supported.
The maximum total size of all transferred files is 4 GB.
The maximum number of files and folders that can be transferred at a time is 10,000.
If a received file has the same name as a file that exists locally, the system might try to overwrite the file. However, if the file to be overwritten has the attribute Read only, Hidden file, or System file, the file cannot be overwritten and file transfer fails.
You cannot specify a Windows UNC path or a network drive as the source or destination of a file transfer.
On the machine where Ops Center Automator is installed and the connection-destination host, in addition to the free space needed for the files and folders themselves, an amount of free space equivalent to twice the size of the transferred files is required as a temporary work area. The temporary work area is as follows:
- For the machine where Ops Center Automator is installed (non-cluster environment): The drive where Ops Center Automator is installed.
- For the machine where Ops Center Automator is installed (cluster environment): The shared disk.
- When the connection-destination is running Windows: The system drive.
- When the connection-destination is running Linux OS: The folder specified in the plugin.remoteCommand.workDirectory.ssh key in the properties file config_user.properties).
The limitations of the OS override those set in the Ops Center Automator system. Examples of these limitations include the maximum size of a file, the number of files per folder, the length of file and folder names, and the resources available to the user. File forwarding that exceeds the limitations of the OS is outside the scope of product support. The OSs whose limitations affect Ops Center Automator are those on the Ops Center Automator server and on operation target devices. The OS limitations that govern which resources are available to users are those set for the connection user and for users with root privileges. Limitations for users with root privileges only apply in Linux OS.
When you specify a folder on a host running Linux OS as the file-transfering destination, the process might fail if the total size of the files in the folder exceeds the maximum permitted size for one file. The maximum size for one file is governed by file system restrictions and OS limitations that apply to the resources available to the user. Ops Center Automator archives files before sending them, which means that the limits of the destination host might be exceeded despite the individual files in the archive being smaller than the maximum size. In this scenario, either reduce the total size of the files in the folder you are sending, or increase the limits at the destination.
If execution of a task is stopped during plug-in execution, the status of the task becomes Failed or Completed when the processing of the File-Transfer Plug-in has finished. The status of steps and tasks after plug-in execution has finished depends on the return code of the step and the condition for executing subsequent steps. You can set Subsequent-step Execution Condition in the Create Step dialog box or the Edit Step dialog box.

Return codes

The following return codes are generated by the File-Transfer Plug-in:

Return Code	Description
0	Ended normally.
65	The connection with the Ops Center Automator server failed. For example, the Ops Center Automator server might have stopped while the plug-in was executing.
66	The following user is mapped to the Ops Center Automator user: A user who does not belong to the Administrators group. A user other than the built-in Administrator who belongs to the Administrators group, in an environment with UAC enabled.
68	No information about the target job execution ID exists.
69	An environment variable of the task-processing engine cannot be acquired.
70	The connection with the operation target device failed.
71	An attempt to call a command on the operation target device failed.
72	The execution status of the command cannot be acquired.
73	The file or folder cannot be transferred.
76	The connection timed out.
77	The host name of the operation target device cannot be resolved.
78	Authentication with the operation target device failed for one of the following reasons: Password authentication failed. Public key authentication has not been set up on the operation target device. When the public key was being authenticated, the private key did not match the pass phrase. When the public key was being authenticated, the private key did not correspond to the public key registered in the operation target device. When the public key was being authenticated, a private key was used that is not valid.
80	Task execution has stopped.
81	The plug-in was called in a status that is not valid.
82	The request message from the task-processing engine annot be correctly parsed.
83	The environment of the Ops Center Automator server is corrupted.
84	Information about the specified plug-in cannot be obtained.
86	The specified property value is not valid.
127	Another error has occurred.

Property list

The following properties are available for the File-Transfer Plug-in:

Property key	Property name	Description	I/O type
remoteHost ^R	Remote Host	Specify the IPv4 address, IPv6 address, or host name of the operation target device. The host name must be within 1,024 characters. The Ops Center Automator server and the operation target device must be connected by a network. Note that multiple IP addresses or host names cannot be specified.	Input
credentialType ^R	Credentials Type	As the authentication type to use during command or script execution, specify either of the following: Destination Specify this option to use the authentication information set in the Agentless Remote Connections view. Specifying destination applies the authentication information set for Windows or SSH in the connection destination definition according to the IP address of the Ops Center Automator logon user. You can omit the specification of properties relating to authentication information (account, password, suPassword, publicKeyAuthentication), and keyboardInteractiveAuthentication. Property Specify this option to use the values specified in the following properties as authentication information: account password suPassword publicKeyAuthentication keyboardInteractiveAuthentication The default value is destination	Input
account	User ID	Specify the user ID to use to log on to the operation target device, using a maximum of 256 characters. You can also specify a domain user in either of the following formats: domain-name \ user-name user-name @ domain-name	Input
password	Password	Specify the password to use to log on to the operation target device, using a maximum of 256 characters. You can omit this property when the operation target device is running Linux OS and true is specified for the publicKeyAuthentication property.	Input
suPassword	Root Password	If the OS of the operation target device is Linux, specify the root password using a maximum of 256 characters. If the OS is Windows, this property does not need to be specified. You can also omit this property when the operation target device is running Windows, or when false is specified for the elevatePrivileges property.	Input
publicKeyAuthentication	SSH public key authentication settings	If the OS of the operation target device is Linux, specify either of the following depending on whether you want to use public key authentication. The values are not case sensitive. If you do not specify a value, false is assumed. You can omit this property when the operation target device is running Windows. true Specify this option to use public key authentication. false Specify this option to use password or keyboard interactive authentication. The default value is false.	Input
keyboardInteractiveAuthentication	SSH keyboard interactive authentication settings	Controls whether to use SSH keyboard interactive authentication for the Linux OS environment. If the OS of the destination is Linux, the system toggles between using and not using keyboard interactive authentication. If the property is set to true, keyboard interactive authentication is used. If the property is set to false, keyboard interactive authentication is not used. This property is not case-sensitive. This property is valid only when publicKeyAuthentication is set to false. If this property does not exist (which is true for a previous plug-in version) or if no value is specified, false is assumed for the property. The default value is false.	Input
elevatePrivileges	Elevate Privileges	If the OS of the operation target device is Linux, specify either of the following depending on whether you want to elevate the user to root privileges. The values are not case sensitive. If you do not specify a value, true is assumed. You can omit this property when the operation target device is running Windows. true Specify this option to run commands as a user with root privileges. false Specify this option to run commands without elevating the user to root. Commands are run with the privileges of the connection user. The default value is false.	Input
transferMode ^R	Transfer Mode	Specify either of the following as the transfer mode: send Specify this option when transferring a file or folder from the Ops Center Automator server to the operation target device. When you specify a file path in the localFilePath property, the same path must be specified in the remoteFilePath property. When transferring a single file, if you specify different file names in the localFilePath and remoteFilePath properties, the file name specified in the remoteFilePath property applies. receive Specify this option when transferring a file or folder from the operation target device to the Ops Center Automator server. When you specify a file path in the remoteFilePath property, the same path must be specified in the localFilePath property. When transferring a single file, if you specify different file names in the remoteFilePath and localFilePath properties, the file name specified in the localFilePath property applies. The default value is send.	Input
localFilePath ^R	Local File Path	Specify the absolute path of the file or folder on the Ops Center Automator server using no more than 256 characters. In the localFilePath property, specify characters that can be used in commands in the OSs of the Ops Center Automator server and the operation target device. If there is a file or folder with the same name in the destination folder, the file or folder is overwritten. For this reason, you should specify a unique name. If the destination folder does not exist, the folder will be created in the specified configuration.	Input
remoteFilePath ^R	Remote File Path	Specify the absolute path of the file or folder on the operation target host in no more than 256 characters. In the remoteFilePath property, specify characters that can be used in commands in the OSs of the Ops Center Automator server and the operation target device. If the OS of the operation target device is Linux, make sure that the names of the files and folders you are transferring are encoded in the same character set used by the connection user. If there is a file or folder with the same name in the destination folder, the file or folder is overwritten. For this reason, you should specify a unique name. If the destination folder does not exist, the folder will be created in the specified configuration.	Input
^R: Required

When specifying file paths, use characters that can be used in commands in the OSs of the Ops Center Automator server and the operation target device. When specifying a file name in the localFilePath property, also specify a file name in the remoteFilePath property. When specifying a folder name in the localFilePath property, also specify a folder name in the remoteFilePath property.

Restrictions apply to the files and folders you can specify in the localFilePath and remoteFilePath properties.

If the operation target device is running Windows and a file with the Windows file attribute "Encrypt contents to secure data" is included among the transferred files, the transfer of the file fails, causing an error in the processing of the plug-in.

Restrictions on the names of transferred files and folders

The following table lists the restrictions that apply to the names of transferred files and folders when the connection destination is Windows or Linux OS:

Table. Sending
File or folder	Ops Center Automator side or destination host side	Property	Restrictions
File	Ops Center Automator	localFilePath	File names can be a maximum of 127 characters.
File	Destination host	remoteFilePath	File names can be a maximum of 127 characters.
Folder	Ops Center Automator	localFilePath	The longest absolute path of the file or folder in the transferred folder can contain no more than 256 characters. The longest path from the folder being transferred to a file or folder under that folder must be no longer than 127 characters.
Folder	Destination host	remoteFilePath	The longest absolute path of the file or folder in the transferred folder can contain no more than 256 characters. The longest path from the folder being transferred to a file or folder under that folder must be no longer than 127 characters.

Table. Receiving
File or folder	Ops Center Automator side or destination host side	Property	Restrictions
File	Ops Center Automator	localFilePath	File names can be a maximum of 127 characters.
File	Destination host	remoteFilePath	File names can be a maximum of 127 characters.
Folder	Ops Center Automator	localFilePath	The longest absolute path of the file or folder in the transferred folder can contain no more than 256 characters. The longest path from the folder being transferred to a file or folder under that folder must be no longer than 127 characters.
Folder	Destination host	remoteFilePath	The longest absolute path of the file or folder in the transferred folder can contain no more than 256 characters. The longest path from the folder being transferred to a file or folder under that folder must be no longer than 127 characters.

Specifying the SSH port number

You can specify a port number when using SSH to connect to the operation target device. The following table describes how to specify the port number and the priority of each method.

Priority	Set in	Property key	Default value
1	Connection-destination properties file (connectiondestination-name.properties)	ssh.port	--
2	Properties file (config_user.properties)	ssh.port.number	22

Specifying the SSH file transfer protocol

You can specify whether to use SFTP when using SSH to connect to the operation target device. If SFTP is not used, SCP is used.

The following table describes how to specify and the priority of each method.

Priority	Set in	Property key	Default value
1	Connection-destination properties file (connectiondestination-name.properties)	sftp.enable	--
2	Properties file (config_user.properties)	plugin.sftp.enable	false

Handling of forwarded files

Forwarded files are handled differently depending on the OS of the operation target device and the value specified in the transferMode property. The following table describes how forwarded files are handled:

Table. Windows
Item			send	receive
Time stamp of forwarded file	When creating a file	Creation date and time	Date and time of forwarding	Date and time of forwarding
		Update date and time	Update date and time of source file	Update date and time of source file
		Access date and time	Date and time of forwarding	Date and time of forwarding
	When overwriting a file	Creation date and time	Creation date and time of overwritten file	Creation date and time of overwritten file
		Update date and time	Update date and time of source file	Update date and time of source file
		Access date and time	Access date and time of overwritten file	Access date and time of overwritten file
Access permissions required for source file			System account read privilege	System account read privilege
Access permissions required for parent folder of destination file			Write privilege of the user set in the authentication information	System account write privilege
Access permissions required for destination file when overwriting the file			Write privilege of the user set in the authentication information	System account write privilege
Access permission assigned to destination file	When creating a file		Inherits privilege of parent folder	Inherits privilege of parent folder
Access permission assigned to destination file	When overwriting a file		Inherits privilege of overwritten file	Inherits privilege of overwritten file

Table. Linux
Item			send	receive
Time stamp of forwarded file	When creating a file	Creation date and time	Date and time of forwarding	Date and time of forwarding
		Update date and time	Date and time of forwarding	Date and time of forwarding
		Access date and time	Date and time of forwarding	Date and time of forwarding
	When overwriting a file	Creation date and time	Date and time of forwarding	Creation date and time of overwritten file
		Update date and time	Date and time of forwarding	Date and time of forwarding
		Access date and time	Access date and time of overwritten file	Access date and time of overwritten file
Access permissions required for source file			System account read privilege	Read privilege of connection user
Access permissions required for parent folder of destination file			Write privilege of connection user	System account write privilege
Access permissions required for destination file when overwriting the file			Write privilege of connection user	System account write privilege
Access permission assigned to destination file	When creating a file		Uses the umask value of root or the connection user	Inherits privilege of parent folder
Access permission assigned to destination file	When overwriting a file		Inherits privilege of overwritten file	Inherits privilege of overwritten file