4.2.3 File-Transfer Plug-in
Function
This plug-in enables forwarding of a file or folder from the JP1/AO server to the operation target device, and vice versa. Files are forwarded in binary mode.
If you have pre-set authentication information in the Agentless Connection Destinations area, you can execute 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 JP1/AO 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 operating systems of the JP1/AO server and the operation target device. For example, if the JP1/AO server and the operation target device are both running the Japanese version of Windows, characters in the MS932 character set can be specified.
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 UNIX, 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 that 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.
For details about how version 01.52.01 of the plug-in differs from previous versions, see A.1 Functional differences between basic plug-ins by version.
Prerequisites for execution
-
For details about operation target devices that can be used as agentless connection destinations, see A.1(3) Operation target devices usable as connection destinations.
-
Depending on the OS of the operation target device, configure the environment as follows:
- For Windows
-
-
Make sure that the JP1/AO server and operation target device are able to communicate using the appropriate ports. For details about the port numbers used for communication, see the JP1/Automatic Operation Overview and System Design Guide.
-
Before executing the file-transfer plug-in, enable administrative sharing on the operation target device. For details, see the JP1/Automatic Operation Overview and System Design Guide.
-
- For UNIX
-
-
You can set the port number used by SSH in the connection-destination property file (connection-destination-name.properties) or the user-specified properties file (config_user.properties).
-
On the operation target device, install a SSH server that supports SCP.
-
-
Certain commands must be installed in the operating system of the operation target device before you use the file-transfer plug-in. For details, see the release notes.
Cautionary notes
-
The execution method differs depending on the OS of the operation target device. If the OS is Windows, SMB and RPC are used for execution. If the OS is UNIX, SSH and SCP are used for execution. When you select the protocol in an agentless connection definition, select Windows in Windows, and SSH in UNIX.
-
If the OS of the JP1/AO server is Linux and the OS of the operation target device is Windows, you cannot specify an IPv6 address as a connection destination.
-
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 attempt 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 JP1/AO 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 JP1/AO is installed (non-cluster environment): The drive where JP1/AO is installed.
-
For the machine where JP1/AO is installed (cluster environment): The shared disk.
-
When the connection-destination is running Windows: The system drive.
-
When the connection-destination is running UNIX: The folder specified in the plugin.remoteCommand.workDirectory.ssh key in the user-specified properties file (config_user.properties).
-
-
The limitations of the operating system override those set in the JP1/AO 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 operating system is outside the scope of product support. The operating systems whose limitations affect JP1/AO operation are those on the JP1/AO 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 UNIX.
-
When you specify a folder on a host running UNIX as the file-forwarding 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. JP1/AO 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.
-
When you forcibly terminate a task while the plug-in is running, the processing being executed is immediately forcibly terminated and the task enters Failed status. A return code of 80 appears for the step in the Flow area of the Tasks window. The return code output to the task log depends on the timing in which the task was forcibly terminated.
-
The execution results of the file-forwarding operation when you forcibly terminate a task during plug-in execution are outside the scope of product support.
Version
01.52.01
Tag
File Operations
Return codes
Return code |
Description |
---|---|
0 |
Ended normally. |
65 |
The connection with the JP1/AO server failed. For example, the JP1/AO server might have stopped while the plug-in was executing. |
66 |
The following user is mapped to the JP1 user:
|
68 |
There is no information about the target job execution ID. |
69 |
An environment variable of the task-processing engine could not 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 a command executed on the operation target device could not be acquired. |
73 |
The file or folder could not be transferred. |
76 |
The connection timed out. |
77 |
The host name of the operation target device could not be resolved. |
78 |
Authentication with the operation target device failed for one of the following reasons:
|
80 |
Task execution has stopped. |
81 |
The plug-in was called in an invalid status. |
82 |
The request message from the task-processing engine could not be correctly parsed. |
83 |
The environment of the JP1/AO server is corrupted. |
84 |
Information about the specified plug-in could not be obtained. |
86 |
The specified property value is invalid. |
127 |
Another error has occurred. |
Property list
The following table describes the properties.
Property key |
Property name |
Description |
Default value |
I/O type |
Required |
---|---|---|---|---|---|
remoteHost |
Remote Host |
Specify the IPv4 address, IPv6 address, or host name of the operation target device. The host name should be within 1,024 characters. The JP1/AO server and the operation target device must be connected by a network. Note that multiple IP addresses or host names cannot be specified. |
-- |
Input |
R |
credentialType#1 |
Credentials Type |
As the authentication type to use during file transfer, specify either of the following:
|
destination |
Input |
R |
account#1 |
User ID |
Specify the user ID to use to log in to the operation target device, using a maximum of 256 characters. You can also specify a domain user in either of the following formats:
|
-- |
Input |
O |
password#1 |
Password |
Specify the password to use to log in to the operation target device, using a maximum of 256 characters. If the OS of the operation target device is UNIX, you can omit this property when true is specified for the publicKeyAuthentication property. |
-- |
Input |
O |
suPassword#1 |
Root Password |
If the OS of the operation target device is UNIX, specify the root password using no more than 256 characters. You can omit this parameter if the OS is Windows or false is specified for the elevatePrivileges property. |
-- |
Input |
O |
publicKeyAuthentication#1 |
SSH public key authentication setting |
If the OS of the operation target device is UNIX, 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 applies. You can omit this property when the operation target device is running Windows.
|
false |
Input |
O |
keyboardInteractiveAuthentication#1 |
SSH keyboard interactive authentication setting |
If the OS of the operation target device is UNIX, specify either of the values below, depending on whether you want to use keyboard interactive authentication for connection. 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. Note, however, that the value of the keyboardInteractiveAuthentication property takes effect only if the publicKeyAuthentication property is set to false. If you set the publicKeyAuthentication property to true, public key authentication is used even if you set the keyboardInteractiveAuthentication property to true.
|
false |
Input |
O |
elevatePrivileges#1 |
Elevate Privileges |
If the OS of the operation target device is UNIX, specify either of the following depending on whether you want to elevate the user to root previleges. The values are not case sensitive. If you do not specify a value, true applies. You can omit this property when the operation target device is running Windows.
|
false |
Input |
O |
transferMode |
Transfer Mode |
Specify either of the following as the transfer mode:
|
send |
Input |
R |
localFilePath #3 |
Local File Path |
Specify the absolute path of the file or folder on the JP1/AO server using no more than 256 characters. In the localFilePath property, specify characters that can be used in commands in the operating systems of the JP1/AO 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, we recommend that you specify a unique name. If the destination folder does not exist, the folder will be created in the specified configuration. |
-- |
Input |
R |
remoteFilePath #3 |
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 operating systems of the JP1/AO server and the operation target device. If the OS of the operation target device is UNIX, 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, we recommend that you specify a unique name. If the destination folder does not exist, the folder will be created in the specified configuration. |
-- |
Input |
R |
- #1
-
If the operation target device is the local host on which the local execution function is enabled, the setting of this property is ignored.
- #2
-
If you set false for both the publicKeyAuthentication and keyboardInteractiveAuthentication properties, password authentication is used.
- #3
-
-
When specifying file paths, use characters that can be used in commands in the operating systems of the JP1/AO 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. For details, see Table 4‒2: Restrictions on file and folder names (when the connection destination is running Windows, Linux, or Solaris) and Table 4‒3: Restrictions on the names of transmitted files and folders (when the connection destination is running AIX or HP-UX).
-
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.
-
If the operation target device is running UNIX and you want to use non-ASCII characters in the remoteFilePath property, see A.4 Prerequisites for executing command lines containing non-ASCII characters in UNIX.
-
Restrictions on the names of transferred files and folders
The following tables list the restrictions that apply to the names of transferred files and folders.
Sending or receiving |
File or folder |
JP1/AO side or destination host side |
Property |
Restrictions |
---|---|---|---|---|
Sending |
File |
JP1/AO |
localFilePath |
File names can be a maximum of 127 characters#1 |
Destination host |
remoteFilePath |
File names can be a maximum of 127 characters#1 |
||
Folder |
JP1/AO |
localFilePath |
|
|
Destination host |
remoteFilePath |
|
||
Receiving |
File |
JP1/AO |
localFilePath |
The file name can be no more than 127 characters#1 |
Destination host |
remoteFilePath |
The file name can be no more than 127 characters#1 |
||
Folder |
JP1/AO |
localFilePath |
|
|
Destination host |
remoteFilePath |
|
- #1
-
When the input value is "C:\folder-1\folder-2\file-1", this restriction applies to file-1.
- #2
-
When the input value is "C:\folder-1\folder-2\folder-3", this restriction applies to the path length from C:\ to a file or folder with the longest path under folder-3.
- #3
-
When the input value is "C:\folder-1\folder-2\folder-3", this restriction applies to the path length from folder-3 to a file or folder with the longest path under folder-3.
Sending or receiving |
File or folder |
JP1/AO side or destination host side |
Property |
Restrictions |
---|---|---|---|---|
Sending |
File |
JP1/AO |
localFilePath |
File names can be a maximum of 127 characters#1 |
Destination host |
remoteFilePath |
File names can be a maximum of 96 bytes#1 |
||
Folder |
JP1/AO |
localFilePath |
|
|
Destination host |
remoteFilePath |
|
||
Receiving |
File |
JP1/AO |
localFilePath |
The file name can be no more than 127 characters#1 |
Destination host |
remoteFilePath |
The file name can be no more than 96 bytes#1 |
||
Folder |
JP1/AO |
localFilePath |
|
|
Destination host |
remoteFilePath |
|
- #1
-
When the input value is "C:\folder-1\folder-2\file-1", this restriction applies to file-1.
- #2
-
When the input value is "C:\folder-1\folder-2\folder-3", this restriction applies to the path length from C:\ to a file or folder with the longest path under folder-3.
- #3
-
When the input value is "C:\folder-1\folder-2\folder-3", this restriction applies to the path length from folder-3 to a file or folder with the longest path under folder-3.
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 property file (connection-destination-name.properties) |
ssh.port |
-- |
2 |
User-specified properties file (config_user.properties) |
ssh.port.number |
22 |
- Legend:
-
--: No value is set.
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.
Item |
Windows |
UNIX |
||||
---|---|---|---|---|---|---|
send |
receive |
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 |
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 |
Date and time of forwarding |
Date and time of forwarding |
||
Access date and time |
Date and time of forwarding |
Date and time of forwarding |
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 |
Date and time of forwarding |
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 |
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 date and time of overwritten file#1 |
Access date and time of overwritten file |
||
Access permissions required for source file |
System account read privilege |
System account read privilege |
System account read privilege |
Read privilege of connection user#2 |
||
Access permissions required for parent folder of destination file |
Write privilege of the user set in the authentication information |
System account write privilege |
Write privilege of connection user#2 |
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 |
Write privilege of connection user#2 |
System account write privilege |
||
Access permission assigned to destination file |
When creating a file |
Inherits privilege of parent folder |
Inherits privilege of parent folder |
Uses the umask value of root or the connection user |
Inherits privilege of parent folder |
|
When overwriting a file |
Inherits privilege of overwritten file |
Inherits privilege of overwritten file |
Inherits privilege of overwritten file#3 |
Inherits privilege of overwritten file |
- #1
-
When the OS of the operation target device is HP-UX, the date and time of the transfer is set.
- #2
-
You do not need to specify privileges when transferring files as the root user.
- #3
-
When the OS of the operation target device is HP-UX, the operation is subject to the umask value of the root user or the connection user.
Related topics
-
Prerequisites for connection destinations in the JP1/Automatic Operation Overview and System Design Guide.
-
User-specified properties file (config_user.properties) and Connection-destination property file (connection-destination-name.properties) in the JP1/Automatic Operation Configuration Guide