IBM Support

CLI copy command for IBM DataPower appliance

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

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.

[{"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)"}]

Document Information

Modified date:
08 June 2021

UID

swg21250655