Cache -change utility

From Messaging Server Technical Reference Wiki
Jump to: navigation, search

Change Job Controller option effective values for the currently running Job Controller process.

Syntax

  imsimta cache -change

imsimta cache -change Command Switches
Switch Default
-global
-debug=n
-max_messages=n
-template=name
-master_job=command
-slave_job=command
-channel=name
-thread_depth=n
-job_limit=n
-parallel_rebuild=n -parallel_rebuild=12
-inorder_rebuild -noinorder_rebuild

Parameters

None.

Description

(New in MS 6.2.) The imsimta cache -change utility is used to change various Job Controller option effective values "on the fly" (that is, without requiring a restart of the Job Controller in order to take effect) for the currently running Job Controller process.

Exactly one of -channel, -template, or -global must be specified. -channel is for changing the behavior or definition of a particular channel: changing its effective maxjobs (-job_limit) or threaddepth (-thread_depth), or its master_command (-master_job) or slave_command (-⁠slave_job). -template is for adding a new type of channel, or for changing the definition of all channels of that type: (re)defining its master_command (-master_job) and/or slave_command (-slave_job). -global is for setting certain global Job Controller options: debug, max_cache_messages (-max_messages), or (6.2p2 and later?) rebuild_parallel_channels (-parallel_rebuild).

Note that restarting the Job Controller is very much to be avoided on a production MTA that has messages already in its queues. So for certain sorts of Job Controller configuration changes that one might want to make on a running MTA, especially configuration changes to trace down problems (debugging) or re-deploy resources at times of heavy load (change channel maxjobs via -job_limit or channel threaddepth via -thread_depth, or define new channels which one has added to the configuration to deal with additional load), it is desirable to make such changes "on the fly". This utility exists to allow making those changes that are both desirable, and feasible without too much disruption to existing Job Controller data structures.

Switches

-channel=name

Change a configuration setting for an existing channel, or inform the Job Controller of the name of a new channel (of a valid, already defined type) that has been added to the configuration.

-debug=n

Set a debug level for Job Controller operation. -global must be specified in order to use -⁠debug.

-global

Set certain global Job Controller options.

-inorder_rebuild, -noinorder_rebuild

-inorder_rebuilddirects the Job Controller to rebuild the message list in order. The -global switch must be specified in order to use -⁠inorder_rebuild. -noinorder_rebuild (the default) means to not rebuild the queues in order: to simply insert messages into the queue cache in whatever order they are encountered while scanning the queue area.

-job_limit=n

The -channel=name switch must be specified in order to use -job_limit; override the effective maxjobs/job_limit for the specified channel.

-max_messages=n

Override the effective max_cache_messages value, or any previously set -max_messages value. -global must be specified in order to use -max_messages.

-master_job=command

Specify the command to execute (channel program to run) for the master direction of a channel. This switch may be used either with the -channel switch, to set the value for a particular channel, or with the -template switch, to set the value for a class of channels.

-slave_job=command

Specify the command to execute (channel program to run) for the slave direction of a channel. This switch may be used either with the -channel switch, to set the value for a particular channel, or with the -template switch, to set the value for a class of channels.

-parallel_rebuild=n

Override the value of the rebuild_parallel_channels Job Controller option. -global must be specified in order to use -parallel_rebuild.

-template=channel-pattern

Define a new type of channel, or redefine an existing type of channel. If redefining an existing type, all channels derived from that template are affected. The argument to -template should be a channel pattern; e.g., tcp_*.

-thread_depth=n

The -channel=name switch must be specified in order to use -thread_depth; override the effective threaddepth for the specified channel.

Examples


# imsimta cache -change -global -debug=7

The above (UNIX) command turns on Job Controller debugging, at level 7.:


# imsimta cache -change -channel=tcp_special

This command informs the Job Controller of a new tcp_special channel that has been added to the configuration (in Unified Configuration, added using msconfig via an edit channels command or via appropriate set channel:tcp_special.* commands; in legacy configuration, added to the imta.cnf file). That is, this imsimta cache -change command does not in and of itself define the channel -- definition of the channel must be performed as normal; however, this command informs the Job Controller of the new channel, so that the Job Controller will know to begin running the channel, as needed.


See also: