Hitachi

JP1 Version 12 JP1/Automatic Operation Service Template Reference


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:

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

Cautionary notes

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:

  • 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

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:

  • 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, an invalid private key was used.

  • Keyboard interactive authentication failed.

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

Specify this option to use the authentication information set in the Connection Destinations area. Specifying destination applies the authentication information set for Windows or SSH in the connection destination definition according to the IP address of the JP1/AO login 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

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:

  • domain-name \ user-name

  • user-name @ domain-name

--

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.

true

Specify this option to use public key authentication.

false

Specify this option to not use public key authentication.#2

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.

true

Specify this value to use keyboard interactive authentication.

false

Specify this value to not use keyboard interactive authentication.#2

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.

true

Specify this option to transfer files or folders as a user with root privileges.

false

Specify this option to transfer files or folders without elevating the user to root. The file or folder will be sent subject to the privileges of the connection user.

false

Input

O

transferMode

Transfer Mode

Specify either of the following as the transfer mode:

  • send

    Specify this option when transferring a file or folder from the JP1/AO 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 JP1/AO 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.

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

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.

Table 4‒2: Restrictions on file and folder names (when the connection destination is running Windows, Linux, or Solaris)

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

  • The longest absolute path of the file or folder in the transferred folder can contain no more than 256 characters#2

  • The longest path from the folder being transferred to a file or folder under that folder must be no longer than 127 characters#3

Destination host

remoteFilePath

  • The longest absolute path of a file or folder in the transferred folder at the destination can contain no more than 256 characters#2

  • The longest path from the transmitted folder at the destination to a file or folder under that folder must be no longer than 127 characters#3

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

  • The longest absolute path of the file or folder in the transferred folder can contain no more than 256 characters#2

  • The longest path from the folder being transferred to a file or folder under that folder must be no longer than 127 characters#3

Destination host

remoteFilePath

  • The longest absolute path of the file or folder in the transferred folder at the destination contain no more than 256 characters#2

  • The longest path from the transferred folder at the destination to a file or folder under that folder must be no longer than 127 characters#3

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

Table 4‒3: Restrictions on the names of transmitted files and folders (when the connection destination is running AIX or HP-UX)

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

  • The longest absolute path of a file or folder in the transferred folder can contain no more than 256 characters#2

  • The longest path from the folder being transferred to a file or folder under that folder must be no longer than 127 characters#3

Destination host

remoteFilePath

  • The longest absolute path of a file or folder in the transferred folder at the destination can contain no more than 256 characters#2

  • The longest path from the transferred folder at the destination to a file or folder under that folder must be no longer than 96 bytes#3

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

  • The longest absolute path of a file or folder in the transferred folder can contain no more than 256 characters#2

  • The longest path from the folder being transferred to a file or folder under that folder must be no longer than 127 characters#3

Destination host

remoteFilePath

  • The longest absolute path of a file or folder in the transferred folder at the destination can contain no more than 256 characters#2

  • The longest path from the transferred folder at the destination to a file or folder under that folder must be no longer than 96 bytes#3

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

Table 4‒4: Priority of SSH port numbers

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.

Table 4‒5: Handling of forwarded files

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