IBM Tivoli Monitoring, Version 6.3

tacmd putfile

Description

Use the putfile command to transfer a file from a local source to a remote managed system.

Note: Do not run more than 10 concurrent getfile, putfile, executeaction, or executecommand operations, in any combination. These 10 concurrent operations apply to both different agents and different physical machines. This command is recommended for transfers of 16 MB or less although not limited to this transfer size.

Transfer file sizes exceeding this limit can require additional response time and IBM Tivoli Monitoring environment consumption. If the getfile, putfile, executeaction and executecommand operations will be executed frequently, monitor the CPU utilization and network activity of the hub monitoring server and remote monitoring servers before and during these operations to ensure that resource consumption is acceptable. If resource consumption is too high, consider reducing the number of concurrent operations and the frequency of the operations.

Note: On the destination endpoint machine, ensure that system's defined temporary directory has sufficient space to temporarily contain the transferred file. The temporary directory is defined by the %TEMP% or %TMP% environment variable for Windows systems, and is the /tmp directory for UNIX and Linux systems.

The hub monitoring server, the targeted monitoring agents, and any remote monitoring servers to which the targeted agents are connected must be at IBM Tivoli Monitoring v6.2.2 Fix Pack 2 or later. If the Tivoli Enterprise Monitoring Agent component is at the IBM Tivoli Monitoring v6.2.2 Fix Pack 2 or later level, all the agents installed in the same CANDLEHOME directory at the endpoint are capable of handing this command. For this command, the specified system cannot be an i5/OS or z/OS monitoring agent.

Hub server configured with non-default port number

The executecommand, getfile, and putfile commands fail if the HUB TEMS is configured with a non-default port number. You must set the environment variable KDE_TRANSPORT in the Windows command prompt or UNIX Shell before issuing these commands to configure the TACMD to use the non-default port number to connect to the hub monitoring server. See the “KDE_TRANSPORT Structure” section of the “Configuring IBM Tivoli Monitoring components” chapter in the IBM Tivoli Monitoring: Installation and Setup Guide for descriptions and examples.

Relative and absolute path support at the endpoint

When running this command between a UNIX or Linux system and targeting a Windows monitoring agent, you must replace the backslashes with forward slashes in the path definitions for the -d|--destination option. It is best to use forward slashes for tolerance with Windows systems. For example, if you want to run the command from a UNIX system to place the monitor agent's configuration file in the C:\IBM\ITM\tmaitm6 directory on a Windows system, use the following command: 
./tacmd putfile -m Primary:WINDOWS:NT -s ./kntenv -d C:/IBM/ITM/tmaitm6/kntenv 
-t text

File names

When either the remote file's directory or name and the destination file's directory or name contain spaces, you must include double quotation marks around the respective directory and file name. For example, run the following command from a UNIX system to place the monitoring agent's configuration file in the C:\Program Files\ITM\tmaitm6 directory 
./tacmd putfile -m Primary:WINDOWS:NT -s /opt/IBM/ITM/kntenv 
-d "C:/Program Files/ITM/tmaitm6/kntenv" -t text
When working with file and directory names that have nonalphanumeric or special characters (for example, ! @ #, etc), the path and file references for either the -s|--source or -d|--destination option must be surrounded by double quotation marks (" "). However, paths that include an at symbol (@) must be escaped with an at symbol (@). The path user@home@directory is escaped as follows: 
user@@home@@directory

Variable substitution

You can run this command by using an environment variable for both the -d|--destination and the -s|--source options. If used for the -d|--destination option, it is for the specified monitoring agent's managed system rather than the local environment where the command is issued. If used for the -s|--source option, it is for the local environment where the command is issued.

The environment variable format is @NAME@. The following characters are valid as the first character of any name, or any subsequent character:
  • _ (underscore)
  • Lower case alphabetic letters
  • Upper case alphabetic letters
The following characters are valid as any character in any name except the first:
  • - (dash)
  • The following numbers, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9
In the following example, CANDLEHOME on the local machine is /opt/IBM/ITM and CANDLE_HOME on the managed system is c:\IBM\ITM: 
./tacmd putfile -m Primary:WINDOWS:NT -s @CANDLEHOME@/kntenv 
-d @CANDLE_HOME@/tmaitm6/kntenv -t text
Note:
  1. For monitoring agents running on AIX 6.1 systems as a root user, it is possible to issue a tacmd putfile command for files having permission 000.
  2. To use this command, the KT1_TEMS_SECURE configuration parameter must be set in the hub monitoring server's configuration file to specify that the hub monitoring server supports this command. After setting the environment variable, you must recycle the hub monitoring server. The default value is no. Specify Y or YES or y or yes if you want to use this command.

CLI syntax

tacmd putfile
                        {-m|--system} SYSTEM  
                        {-s|--source} LOCAL_FILE
                        {-d|--destination} REMOTE_FILE
                        [{-t|--type} MODE]
                        [{-f|--force}]

where:
-m|--system
Specifies to which managed system to put the file. This must be a monitoring agent. Use the listsystems command to receive a list of which systems are available. Valid values include letters (upper or lower case), numbers, periods (.), at symbols (@), dollar signs ($), asterisks (*), number signs (#), underscores (_), colons (:) or blanks ( ).
-s|--source
Specifies the local file name. Environment variables are supported. When specifying the source option, it must be an existing path. If the path is not specified, the default path is relative to where the command is issued.
-d|--destination
Specifies the remote file name. Environment variables are supported. When specifying the destination option, it must be an existing path. If the path is not specified, the default path is the CANDLEHOME/kt1v3depot/product_code directory on the endpoint
-t|--type
Specifies the MODE of transfer. MODE can be bin or text. If not specified, the default is bin. Specify text mode if the file is a human readable file, otherwise, specify bin (binary) mode.
-f|--force
Overwrites the remote file as specified by –d|--destination option if it already exists.

CLI example

See the example in the description of this command.

Return values

See Table 1.

Related commands

tacmd getfile

Return to Table 1.


Feedback