fteModifyAgent: run an MFT agent as a Windows service

The fteModifyAgent command modifies an existing agent so that it can be run as a Windows service. This command is only available on Windows.

Important: On IBM MQ for Multiplatforms, only users who are IBM MQ administrators (and members of the mqm group) can run this command. If you try to run this command as a user who is not an IBM MQ administrator, we will receive the error message BFGCL0502E: You are not authorized to perform the requested operation. and the command will not run. On z/OS systems, the user must satisfy (at least) one of these conditions in order to run the migrate command:

  • Be a member of the mqm group (if the mqm group is defined on the system).
  • Be a member of the group named in the BFG_GROUP_NAME environment variable (if one is named).
  • Have no value set in the BFG_GROUP_NAME environment variable when the command is run.


Syntax

fteModifyAgent

fteModifyAgent-agentName  agent_name-p configuration_options-s service_name-su user_name-sp password-sj options-sl options-n


Parameters

    -agentName agent_name
    Required. The name of the agent we want to modify.

    -p configuration_options
    Optional. This parameter determines the set of configuration options that is used to modify the agent. By convention use the name of a non-default coordination queue manager as the input for this parameter. The fteModifyAgent command then uses the set of properties files associated with this non-default coordination queue manager.

    Specify the optional -p parameter only if we want to use configuration options different from your defaults. If we do not specify this parameter, the set of configuration options based on the default coordination queue manager is used.

    -s service_name
    Optional. Indicates that the agent is to run as a Windows service. If we do not specify service_name, the service is named mqmftAgentAGENTQMGR, where AGENT is the agent name and QMGR is your agent queue manager name.

    The display name for the service, which is shown in the Windows Services window in the Name column, is always Managed File Transfer Agent AGENT@QMGR.

    Note: If the redistributable agent is going to run as a Windows service, then the BFG_DATA environment variable needs to be set in the system environment for the service to work.

    -su user_name
    Optional. When the agent is to run as a Windows service, this parameter specifies the name of the account under which the service should run. To run the agent using a Windows domain user account specify the value in the form DomainName\UserName. To run the service using an account from the local built-in domain specify the value in the form UserName.

    The Windows user account that you specify using the -su parameter must have the Log on as a service right. For information about how to grant this right, see Guidance for running an MFT agent or logger as a Windows service.

    This parameter is required when -s is specified. Equivalent to -serviceUser.

    -sp password
    Optional. Password for the user account set by the -su or -serviceUser parameter.

    This parameter is only valid when -s is specified. Equivalent to -servicePassword. If you do not specify this parameter when you specify the -s parameter, a warning message is produced. This message warns you that we must set the password using the Windows Services tool before the service will start successfully.

    -sj options
    Optional. When the agent is started as a Windows service, this parameter defines a list of options in the form of -D or -X that will be passed to the Java Virtual Machine (JVM). The options are separated using the number sign (#) or semicolon (;) character. For to embed any # or ; characters, put them inside single quotation marks.

    For more information about the way in which the fteModifyAgent command handles the validation of updates to the JVM options that are specified with the -serviceJVMOptions parameter, see Guidance for updating agent or logger JVM options.

    This parameter is only valid when -s is specified. Equivalent to -serviceJVMOptions.

    -sl options
    Optional. Sets the Windows service log level. Valid options are: error, info, warn, debug. The default is info. This option can be useful if we are having problems with the Windows service. Setting it to debug gives more detailed information in the service log file.

    This parameter is only valid when -s is specified. Equivalent to -serviceLogLevel.

    -n
    Optional. Indicates that the agent is to be run as a normal process. This is mutually exclusive with the -s option. If neither the -s nor the -n option is specified, then the agent is configured as a normal Windows process.

    Equivalent to -normal.

    -? or -h
    Optional. Displays command syntax.


Example

In this example, AGENT1 is modified to run as a Windows service: 
fteModifyAgent -agentName AGENT1 -s -su fteuser -sp ftepassword
In this example, AGENT1 is modified to remove the Windows service: 
fteModifyAgent -agentName AGENT1

We must stop the agent you want to modify, using the fteStopAgent command, before we can run the fteModifyAgent command.


Return codes

    0
    Command completed successfully.

    1
    Command ended unsuccessfully.

Parent topic: MFT commands


Related reference


Related information