Installing BMC Defender File Transfer Queue adapter

BMC delivers the BMC Defender File Transfer Queue adapter as a self-extracting WinZip file and you install the adapter manually. No automatic installation is provided. 

This topic contains the following information:

Installation requirements

The BMC Defender File Transfer Queue adapter is minimally invasive. You can install it on a variety of platforms and operating systems.

  • Existing BMC Defender Server installation—Before installing the adapter software, you must install the BMC Defender Server system on a Windows platform. For more information, see the BMC Defender Agent for Windows documentation. 
  • Disk space requirements—The software requires no significant disk space beyond the normal footprint of the BMC Defender Server. There is generally no extra disk space load due to this software.
  • CPU requirements—A single process starts the BMC Defender Windows platform. Therefore, the software consumes minimal CPU resources.
  • Service ports—The software requires access to the standard syslog port of 514. You should adjust the firewalls to accommodate this service port and communication channel between CO-queue.exe program and the BMC Defender Server.

Administrative logins are required to perform the software installation. 

To ensure proper installation of the program, perform the following steps:

  • Close all windows.
  • Temporarily disable any port blocking or virus scan software on the system.
  • Stop the existing BMC Defender Server process.

You are not required to restart the system after installation.

To install the adapter with the self-extracting WinZip file

  1. Stop the BMC Defender Framework service via the Service Manager or the BMC Defender Stop Service utility.
  2. Obtain the BMC Defender File Transfer Queue adapter software in self-extracting WinZip format. You can obtain the file directly from BMC Support.
  3. Run the self-extracting WinZip file. Running this file:
    • Unzips the software into the BMC Defender Windows Distribution, including all configuration data, executables, and documentations
    • Configures the CO-queue.exe service to start when BMC Defender is restarted
  4. Restart BMC Defender, and 
  5. (Optional) Configures the parameters available for the CO-queue.exe process, including the queue directory, via the BMC Defender Web interface in the Messages > Adapters > File Queue window.
  6. C  onfigures other parts of the BMC Defender system, such as threads, alerts, and ticket users, to correlate and process the syslog messages that are generated by the software.

To install the adapter on the BMC Defender Windows platform

  1. Log on to the BMC Defender Server Windows platform using an Administrator type login.
  2. Stop the BMC Defender Server processes using the Windows Service Manager, or the Start and Stop Services utility found in the Windows Start menu. Verify with the Windows Task Manager that all BMC Defender processes are stopped.
  3. Obtain and execute the co-n-n-n-queue.exe package, extracting files to the directory location where BMC Defender is installed. The default installation directory is C:\Program Files\BMC Software\BMC Defender. This installs the files and configures the CO-queue.exe program to start when the BMC Defender Framework Service is restarted.
  4. Restart the BMC Defender Server processes using the Windows Service Manager, or using the Start and Stop Services utility.
  5. Verify with the Windows Task Manager that the CO-queue.exe process is now running on the system.
  6. Log on to BMC Defender and 
  7. (Optional) Configure process parameters (in particular, the Destination Address value).

To install the adapter as an embedded part of the BMC Defender Server

The procedure in this topic describes how to install the BMC Defender File Transfer Queue adapter as an embedded part of the BMC Defender Server. 

Note

You can install the BMC Defender File Transfer Queue adapter as a separate and stand-alone component without first installing BMC Defender Server.

If you install the BMC Defender File Transfer Queue adapter without first installing BMC Defender Server, you should manually install the CO-queue.exe program as a Windows service and manually edit the configuration file with a text editor to adjust parameters. Manually installing and configuring the BMC Defender File Transfer Queue adapter enables you to implement the file transfer queue on a remote or auxiliary machine (for example, to support distributed management). The CO-queue.exe program can operate as either an embedded BMC Defender process or a standard Windows service. For information about alternate procedures for installing the CO-queue.exe program, see the following sections later in this topic:

To install the adapter on a stand-alone machine

You can use the following procedure to install the CO-queue.exe process externally on a stand-alone machine on which the main BMC Defender Server program is not installed. This provides application in remote management, in which various servers might be feeding complete log file information to a centralized log manager.

Example

Several different copies of the CO-queue.exe program might run on the network, in which each program forwards one or more specific logs to BMC Defender Server at scheduled intervals. Each of these processes can operate stand-alone, without any other BMC software present on the system.

  1. Log on to the target platform using an Administrator type login.
  2. Obtain and execute the co-n-n-n-queue.exe package and extract files to the default location. The default installation directory is C:\Program Files\BMC Software\BMC Defender.
  3. Create a command prompt, change working directories to the  installationDirectory\system directory, and locate the CO-queue.exe program. (The precise location depends on the location to which you extracted the files in Step 2.)

  4. Run the following commands at a command prompt: 

    CO-queue.exe –install
    CO-queue.exe –mode auto
    CO-queue.exe –start

    The given command sequence installs the BMC Defender File Transfer Queue adapter, sets the startup mode to automatically start when the node starts, and then starts the service. After executing the preceding commands, the BMC Defender File Transfer Queue adapter appears in the Windows Service Manager.

  5. Edit the CO-queue.cnf file and set the various values. By default, only the DestinationAddress value needs to be modified.
  6. Copy a text file to the installationDirectory\file-queue directory, and verify that the contents of the file is correctly sent to the Syslog receiver.

To uninstall the program, issue the following commands:

CO-queue.exe –stop
CO-queue.exe –remove

To access help on the CO-queue.exe command arguments

Type the following command:

CO-queue.exe –help

A brief description of the all the available commands for the CO-queue.exe program is displayed:

BMC Defender Message Queue Service.
Copyright 2008 - 2018, CorreLog, Inc.
Copyright 2018 - 2019, BMC Software, Inc. http://www.bmc.com
ALL rights reserved.
Build Date: Thu Sep 12 09:44:27 2019

co-queue.exe -install
co-queue.exe -remove
co-queue.exe -start
co-queue.exe -stop
co-queue.exe -mode auto | manual | disable
co-queue.exe -permit
co-queue.exe -svc

The following table describes the program command options:

Option

Description

-install

Creates and configures the file transfer queue services that are required to monitor and send files

-remove

Stops any file queue services that are running and removes them from the system

You can add the file transfer queue again with the -install command.

-start

Manually starts the file transfer queue services, used with -mode manual

-stop

Manually stop the file transfer queue services

-mode

Sets the startup mode of the file transfer queue:

  • auto—(Default value) Starts the file transfer queue services when the main BMC Defender services are started
  • manual—Starts and stops services only when you use the -start and -stop commands
  • disable—Disables the file transfer queue services and services cannot be started manually or automatically
-permit

Checks if the Windows Service Manager is available

The Windows Service Manager is required to set up the file transfer queue services.

-svc

Runs the main file transfer queue service


The CO-queue.exe program checks for modifications to the configuration file approximately once each five seconds, immediately rereads the configuration data, and applies changes as soon as the configuration file is modified. This process enables you to manually edit the configuration data while the program is running without having to stop and restart the BMC Defender File Transfer Queue adapter.

Note

Multiple copies of the CO-queue.exe program can exist on the network, but only one CO-queue.exe service can be installed per machine without specific configuration. The specific steps needed to install multiple copies of the program on a single machine are described in the next topic.

To install multiple instances of the adapter

The following procedure describes how to install multiple instances of the adapter to run on the same platform. This type of installation might be useful if more than four different queue folders exist on the same platform, or if each queue handles a specific file type that requires a special facility, severity, or other set of configuration parameters.

By default, a single copy of the CO-queue.exe program executes on the platform, that can handle up to four different queue directories (selected through the parameters screen). Using the procedure herein, an additional eight instances of the program can be installed, to expand the number of separate queues to be a total of 32 different folders. Each instance of the service has its own configuration file, queue directory (or directories), transfer log, and gadget.

Example

Using the technique described herein, you can configure a queue directory that prefixes messages with a different value, or sends messages at a different speed. On the BMC Defender Server, completely different processes service the queue.

This special ability relies on you defining a program instance number for each program. The instance number ranges from 1 to 8. For each program instance, you copy the web interface, configuration file, and service program to a new name containing the instance number as a suffix. This is a simple manual process, the specific steps of that are typically performed at a command prompt by the administrator.

The precise steps needed to configure a new file transfer queue instance is as follows:

  1. Install the File Queue Monitor program as described in earlier in this topic.
  2. In the installationDirectory\sigma-web directory, locate the file queue manager web interface program (normally found in 200_Messages.dir\ 450_Adapters.dir\ 450_File_Queue.exe ).

  3. Copy the existing 450_File_Queue.exe program to a new name, incorporating an instance number with the latter, such as: 

    450_File_Queue_1.exe

    This step adds the _1 suffix to the program name, which is the unique instance number for this instance. The value of the instance number can range from 1 to 8.
    After making this change, a new tab appears in the Adapters tab of the program, such as File Queue 1.

  4. In the installationDirectory\system directory, locate the CO-queue.cnf file.

  5.  Copy the existing CO-queue.cnf file to a new name that agrees with the web interface name, such as: 

    CO-queue_1.cnf

    This step adds the _1 suffix to the configuration file, which is the instance number for this instance. The instance number value must agree with the web interface program, created in Step 3.

  6. In the installationDirectory\system directory, locate the CO-queue.exe program.

  7. Copy the existing CO-queue.exe file to a new name that agrees with the web interface name, such as: 

    CO-queue_1.exe

    This step adds the _1 suffix to the actual service name, which is the instance number for this instance. The instance number value must agree with the web interface program, created in Step 3.

  8. In the installationDirectory\s-cgi\gadgets directory, locate the File-Queue-Gadget.exe executable program.

  9.  Copy the existing File-Queue-Gadget.exe file to a new name that agrees with the web interface name, such as: 

    File-Queue-Gadget_1.exe

    This step adds the _1 suffix to the gadget name, which is the instance number for this instance. The instance number value must agree with the web interface program, created in Step 3.

  10. Configure the new instance of the service to start through the BMC Defender System > Schedule screen. If the program is launched by BMC Defender, add a line such as the following to the Schedule screen.

    start CO-queue_1.exe –svc

    See Section #2 for details related to scheduling the service to start. This step is identical to the step outline in Section #2, except the new instance of the program is referenced.
    If you are planning to launch the process by creating a new service manager entry, you can follow the steps in the previous section, operating on the newly renamed executable. This is sufficient to add a new and unique service entry.

These steps are sufficient to create a new instance of the file queue monitor that runs independent of other file queue monitors. You create a separate configuration file, service program, web interface tab, and gadget.

Note

The program automatically detects the proper configuration file based upon the program name, that must be identified in the program through the special _N instance number. (The underscore is required, and the value of N can range between 0 and 8.)

To delete an instance, you simply remove all the files created. You can delete any instance (including the initial instance that does not contain an instance number) without affecting the configuration of the other instances on the system.

Note

Before running a formatter, the FQ_PATHNAME environmental variable is set, that can be used by the formatter batch file (or by an executable program) to specify the name of the file on which to operate.

This section provides information about the following topics:

Related topics

BMC-Defender-File-Transfer-Queue-adapter

Configuring-BMC-Defender-File-Transfer-Queue-adapter

Using-BMC-Defender-File-Transfer-Queue-adapter


 

Tip: For faster searching, add an asterisk to the end of your partial query. Example: cert*