Troubleshooting
Problem
How to use the CLI copy command to transfer a file to and from IBM DataPower Gateway appliance.
Resolving The Problem
Copying a file to and from the IBM DataPower Gateway appliance can be done using the following commands in CLI.
Command : copy
Function: Copies a file to or from the IBM DataPower Gateway appliance flash using one of the following transport protocols: HTTP, HTTPS, SMTP, SCP (Secure Copy), or Secured File Transfer Protocol (SFTP).
Syntax: copy [ -f ] sourceURL destinationURL
In the absence of this argument, an attempt to save a file with the name of an existing file results in a CLI prompt requiring confirmation that you want to overwrite the existing file. With the switch set, an attempt to save a file with the name of an existing file is immediately executed.
sourceURL and destinationURL are URLs that identify the source file and target destination. If the source file or target destination reside on the device flash, sourceURL or
destinationURL take the form:
directory specifies the location on the device (device directories). It could be one of the following:
Note: Both pubcert: and sharedcert: are read-only in any domain other than the default domain. Consequently files can be added to these directories only while in the default domain.
filename specifies the name of a file or target destination within the referenced directory.
If the source file or target destination is remote from the appliance flash and the transport protocol is either SCP or SFTP, sourceURL or destinationURL take the form of an RFC 1738-compliant URL:
<host> can be specified as an IP address or as a qualified host name (assuming that DNS services have been previously enabled). When using SMTP as a transport protocol to the target destination, destinationURL takes the form:
Guidelines:
Also available in Flash Configuration Mode.
When using SCP or SFTP, you will be prompted for a remote login password.
You can use the copy command to transfer any file type to or from the appliance flash.
NOTE: Make sure you are in the global configuration mode while trying to run the following examples. The following command enters global configuration mode:
idg# co
Global configuration mode
idg(config)#
NOTE: For security reasons, you can not invoke SCP or SFTP on a remote machine and have the DataPower appliance be either the source or destination. To use SCP and SFTP to transfer files to the DataPower appliance, you must invoke the copy command on the appliance itself.
Example using HTTP to copy a file from the specified URL to the device firmware image directory:
Note: You cannot use the copy command to copy files from the cert: directory. You cannot use the copy command to copy a file to the audit:, logstore:, or logtemp: directories.
Example using HTTP over an SSL connection to copy a file from the specified URL to the device firmware image directory:
Example using SCP to copy a file from the specified URL to the device general storage directory:
Example using SCP to copy a file from the device logging directory to the specified remote target (identified by a qualified host name and directory path):
(1) Copy file to existing path under user home directory (relative path):
Example using SFTP to copy a file from the specified URL to the device general storage directory:
Example using SFTP to copy a file from the device logging directory to the specified remote target:
Example using SMTP to copy a file from the device audit directory and mail the file to the specified recipient:
Example to copy a file from the local configuration directory to the local user storage directory:
For more information on the copy command, please see the IBM DataPower Gateway Global CLI Command Reference Guide.
Command : copy
Function: Copies a file to or from the IBM DataPower Gateway appliance flash using one of the following transport protocols: HTTP, HTTPS, SMTP, SCP (Secure Copy), or Secured File Transfer Protocol (SFTP).
Syntax: copy [ -f ] sourceURL destinationURL
- -f is an optional switch that forces an unconditional copy.
In the absence of this argument, an attempt to save a file with the name of an existing file results in a CLI prompt requiring confirmation that you want to overwrite the existing file. With the switch set, an attempt to save a file with the name of an existing file is immediately executed.
sourceURL and destinationURL are URLs that identify the source file and target destination. If the source file or target destination reside on the device flash, sourceURL or
destinationURL take the form:
- directory:///filename
directory specifies the location on the device (device directories). It could be one of the following:
audit: | contains the audit log |
cert: | contains domain-specific private keys and certificates |
config: | contains configuration scripts |
export: | contains export packages |
image: | contains primary and secondary firmware images |
local: | contains user processing resources such as stylesheets, schemas, document encryption maps, or XML mapping files |
logstore: | contains logging files |
logtemp: | contains active and rotated log files |
pubcert: | contains well-known (for example, Verisign) public certificate files |
sharedcert: | contains private keys and certificates which are shared across domains |
store: | contains DataPower-supplied processing resources such as stylesheets, schemas and authentication/authorization files |
tasktemplates: | contains Task Template files |
temporary: | contains temporary files |
Note: Both pubcert: and sharedcert: are read-only in any domain other than the default domain. Consequently files can be added to these directories only while in the default domain.
filename specifies the name of a file or target destination within the referenced directory.
If the source file or target destination is remote from the appliance flash and the transport protocol is either SCP or SFTP, sourceURL or destinationURL take the form of an RFC 1738-compliant URL:
- <scp | sftp>://<user>@<host>/<file-path>
<host> can be specified as an IP address or as a qualified host name (assuming that DNS services have been previously enabled). When using SMTP as a transport protocol to the target destination, destinationURL takes the form:
mailto:[email protected]
Guidelines:
Also available in Flash Configuration Mode.
When using SCP or SFTP, you will be prompted for a remote login password.
You can use the copy command to transfer any file type to or from the appliance flash.
NOTE: Make sure you are in the global configuration mode while trying to run the following examples. The following command enters global configuration mode:
idg# co
Global configuration mode
idg(config)#
NOTE: For security reasons, you can not invoke SCP or SFTP on a remote machine and have the DataPower appliance be either the source or destination. To use SCP and SFTP to transfer files to the DataPower appliance, you must invoke the copy command on the appliance itself.
Example using HTTP to copy a file from the specified URL to the device firmware image directory:
- idg(config)# copy
http://host/image.crypt
image:///image.crypt
file copy successful (1534897 bytes transferred)
idg(config)#
Note: You cannot use the copy command to copy files from the cert: directory. You cannot use the copy command to copy a file to the audit:, logstore:, or logtemp: directories.
Example using HTTP over an SSL connection to copy a file from the specified URL to the device firmware image directory:
- idg(config)# copy
https://host/image.crypt
image:///image.crypt
file copy successful (1534897 bytes transferred)
idg(config)#
Example using SCP to copy a file from the specified URL to the device general storage directory:
- idg(config)# copy scp://[email protected]/XML/stylesheets/InitialConvert.xsl store:///InitialConvert.xsl
Password: yetanotherpassword
file copy successful
idg(config)#
- Note : copy over SCP will not work in 3.7.1.x, if "Enforce RBM on CLI" in set to ON in Administration -> RBM settings -> Main tab
Example using SCP to copy a file from the device logging directory to the specified remote target (identified by a qualified host name and directory path):
(1) Copy file to existing path under user home directory (relative path):
- idg(config)# copy logstore:///Week1.log scp://[email protected]/LOGS/x/Week1.log
Password: yetanotherpassword
file copy successful
This example shows that the file "Week1.log" is copied to "LOGS/x" directory under the "test" user home directory path. Please note that directory path "LOGS/x" must exist in user home directory. Otherwise the copy operation will fail as it is using relative directory path.
(2) Copy file to existing path outside of user home directory (absolute path):
idg(config)# copy logstore:///Week1.log scp://[email protected]//LOGS/x/Week1.log
Password: yetanotherpassword
file copy successful
This example shows that the file "Week1.log" is copied to "/LOGS/x" directory under the file system "/" that is outside of "test" user home directory. Please note that directory path "/LOGS/x" must exist in the file system and the user "test" must have the write permission to the directory. Otherwise the copy operation will fail as it is using an absolute directory path.
idg(config)#
Example using SFTP to copy a file from the specified URL to the device general storage directory:
- idg(config)# copy sftp://[email protected]/XML/stylesheets/InitalConvert.xsl store:InitalConvert.xsl
Password: yetanotherpassword
file copy successful
idg(config)#
Example using SFTP to copy a file from the device logging directory to the specified remote target:
- idg(config)# copy logstore:Week1.log sftp://[email protected]/LOGS/x/Week1.log
Password: yetanotherpassword
file copy successful
idg(config)#
Example using SMTP to copy a file from the device audit directory and mail the file to the specified recipient:
- idg(config)# copy audit:audit-log
mailto:[email protected]
File enqueued to '[email protected]' - please verify in system log
idg(config)#
Example to copy a file from the local configuration directory to the local user storage directory:
- idg(config)# copy config:///startup-config local:///startup-config
file copy successful (2347 bytes transferred)
idg(config)#
For more information on the copy command, please see the IBM DataPower Gateway Global CLI Command Reference Guide.
Related Information
[{"Type":"SW","Line of Business":{"code":"LOB45","label":"Automation"},"Business Unit":{"code":"BU053","label":"Cloud & Data Platform"},"Product":{"code":"SS9H2Y","label":"IBM DataPower Gateway"},"ARM Category":[{"code":"a8m50000000CdrrAAC","label":"DataPower->MGMT (MM)->CLI"}],"ARM Case Number":"","Platform":[{"code":"PF025","label":"Platform Independent"}],"Version":"All Version(s)"}]
Was this topic helpful?
Document Information
Modified date:
08 June 2021
UID
swg21250655