Restart utility

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

Restart MTA components.

Syntax

  imsimta restart [component]

Restrictions

Must have superuser privileges or use the Solaris RBAC feature in order to use this utility.

Parameters

component

Optional parameter which specifies a specific MTA component, or Dispatcher service, to be restarted. The components which may be restarted with this utility are job_controller, dispatcher. Any Dispatcher service may be restarted with this utility by specifying the service name; with the services in a typical configuration, this means smtp, smtp_submit, and lmtpss, but any other site-specific services may be restarted similarly by specifying their name. Note that restarting the MTA Dispatcher, i.e., the dispatcher component, effectively restarts all the service components it handles, which may include smtp, smtp_submit, and lmtpss. If no component name is given, then all active components will be restarted. If the asterisk character, *, is specified as the "component", then all active services under the Dispatcher (but not the Dispatcher itself) will be restarted; note that to avoid shell interpretation and get the asterisk character passed through as an argument to the utility itself, it will usually be necessary to quote the asterisk character, "*".

Description

Detached MTA processes should be restarted whenever relevant portions of the MTA configuration are altered---these processes load information from the configuration once only and generally need to be restarted in order for configuration changes to become visible to them. (In legacy configuration, in addition to general MTA configuration files such as the imta.cnf file, note that components such as the Dispatcher have their own specific configuration files, e.g., dispatcher.cnf, and should be restarted after changes to any of these files.) However, note that some configuration changes can be put into effect without a restart: see the imsimta reload and imsimta cache -change utilities.

An imsimta restart command is equivalent to performing a imsimta shutdown followed by an imsimta startup on the specified component.

If no component name is specified, then the imsimta restart utility stops any old Job Controller process and Dispatcher process that might be running, and restarts the Job Controller and Dispatcher. If a component parameter is specified, then only detached processes associated with that component will be restarted. If an asterisk character, *, is specified, then all active services running under the Dispatcher will be restarted (though the Dispatcher itself will not be restarted in this case); note that shell interpretation will usually require that the asterisk character be quoted so that the shell will pass the asterisk through as an argument to the imsimta restart command.

The standard component names are:

Component Names
Component Description
dispatcher MTA multithreaded Dispatcher handling services such as SMTP, SMTP SUBMIT, and LMTP servers.
job_controller MTA Job Controller.
lmtpss LMTP server for Message Store delivery
smtp SMTP server processes.
smtp_submit SMTP SUBMIT (port 587) server processes.

Note that restarts of the Job Controller should be avoided, especially during periods of large message backlogs, unless such a restart is necessary. Note that a restart of the Job Controller requires that the Job Controller rescan the queue directory structure to re-discover all message files, and completely rebuild its internal data structures that control message delivery scheduling and the order of message delivery attempts. Such rescanning and rebuilding of data structures is designed to be fast, and have a low impact on the processing of any newly submitted messages that may come in during the rebuilding. But it is not intended to necessarily restore the exact state of the Job Controller's original scheduling, and in practice a certain degree of "out-of-order" processing of the backlogged messages (messages already existing on disk), and "unfair" division between channels of effort on processing the backlogged messages, is expected to occur after a restart of the Job Controller.

Whenever the Job Controller is shutdown (and a restart includes a shutdown of the "old" Job Controller process), before it shuts down it sends a "no more messages" notice to all its child processes (channel processes), which such processes will see once they finish up whatever current message they are working on and ask the Job Controller whether there are any more messages. That is, the Job Controller itself shuts down, but leaves a "poison" message that the channel jobs will see as they each finish up their own work. So generally (but with a couple of exceptions, to be discussed just below) any old channel processes that the Job Controller had previously started finish up whatever message they had already been working on. Once a channel process has finished its already started work and then asks for another message to process, it will see that there are no more messages for it to process, and exit. However, exceptions are the ims-ms channel, and less commonly, outbound TCP/IP channels. ims-⁠ms channels will interrupt processing even of currently being processed messages after a brief amount of time (an additional 55 seconds) to attempt to complete processing of a current message; the remaining recipients of a message for which processing had begun will be deferred for later processing; (when logging is enabled, "Z" records with a reason, as of MS 8.0, of "shutting down" will be generated for those recipients; note that prior to MS 8.0, the reason was was "shutdown"). TCP/IP channels will abort processing after their configurable WINDDOWN_TIMEOUT channel-specific option time period has expired. (The default value for WINDDOWN_TIMEOUT is relatively "large" due to the potential for undesirable remote SMTP server handling of aborted message transfers, and the potential expense of resending a "large" message.)

Examples


# imsimta restart dispatcher

The above UNIX command restarts the Dispatcher, and hence all services under the dispatcher.


# imsimta restart "*"

The above UNIX command restarts all the services under the Dispatcher (typically SMTP, SMTP_SUBMIT, and LMTPSS) without restarting the Dispatcher itself.


# imsimta restart

The above UNIX command restarts all the MTA jobs, including the Job Controller (and should be avoided unless a restart of the Job Controller is truly needed).


# imsimta restart
Stopping dispatcher server 29615 .. done 
Stopping job_controller server 29637 . done 
Starting dispatcher server . 29645 
Starting job_controller server . 29655 

The above shows the sort of output shown as of MS 6.3, including in particular the pids of the stopped and started processes.


# imsimta restart job_controller
job_controller server is not running 
Starting job_controller server .. 29683 

The above shows the sort of output shown as of MS 6.3, if a restart command is given for the Job Controller when it is not actually currently running.

Error messages

Trouble communicating with the Dispatcher, shutting it down, or restarting it, will be reported back to stderr:


dispatcher server is not running
 

Cannot stop dispatcher server (pid=pid) with SIGTERM
Retrying with SIGKILL
 

dispatcher server is running already

Trouble restarting the Job Controller will be reported back to stderr:


job_controller server is not running
 

job_controller server is running already 

See also: