Applies to: Exchange Server 2007 SP3, Exchange Server 2007 SP2, Exchange Server 2007 SP1, Exchange Server 2007
Topic Last Modified: 2007-07-17

This topic explains how to use the Exchange Management Shell to enable pipeline tracing of e-mail messages as they move through the transport pipeline on computers that have the Microsoft Exchange Server 2007 Hub Transport server role or Edge Transport server role installed.

For more information about pipeline tracing, the transport pipeline, and transport agents in Exchange 2007, see the following topics:

Note:
You cannot administer pipeline tracing by using the Exchange Management Console. To administer pipeline tracing, you must use the Exchange Management Shell. For more information about how to use the Exchange Management Shell, see Using the Exchange Management Shell.

Before You Begin

Caution:
Pipeline tracing copies the complete contents of e-mail messages that are sent from the e-mail account that is configured by using the PipelineTracingSenderAddress parameter on the Set-TransportServer cmdlet. To avoid unwanted exposure of confidential information, you must set appropriate security permissions on the location of the pipeline tracing log file that is specified by the PipelineTracingPath parameter on the Set-TransportServer cmdlet.
Caution:
Do not enable pipeline tracing for long periods of time. Pipeline tracing creates verbose log files that can accumulate quickly. Always monitor available disk space when pipeline tracing is enabled.

To run the Set-TransportServer cmdlet on a computer that has the Edge Transport server role installed, you must be a member of the local Administrators group on that computer.

To run the Set-TransportServer cmdlet, the account you use must be delegated the following:

  • Exchange Organization Administrator role

For more information about permissions, delegating roles, and the rights that are required to administer Exchange 2007, see Permission Considerations.

Configuring the Pipeline Tracing Sender Address

Pipeline tracing generates log files only for e-mail messages that are sent from the Simple Mail Transfer Protocol (SMTP) e-mail address that you specify by using the PipelineTracingSenderAddress parameter on the Set-TransportServer cmdlet. Pipeline tracing does not generate log files for messages that are sent from any other e-mail address. The SMTP e-mail address that you specify can be internal or external to your Exchange organization.

If you want to generate log files for messages that are generated by e-mail servers, such as out-of-office messages, delivery status notification (DSN) messages, journal reports, and other system-generated messages, you can specify the value "<>" with the PipelineTracingSenderAddress parameter.

Caution:
Setting the value for the PipelineTracingSenderAddress parameter to "<>" captures all e-mail server-generated messages that are received by the Hub Transport or Edge Transport server that you are configuring. Depending on the amount of e-mail server-generated messages that your organization receives, this may place a significant load on the server and may quickly consume available disk space. Always monitor available disk space when pipeline tracing is enabled.

After you specify the pipeline tracing sender address, you must enable pipeline tracing. For more information, see the "Enabling Pipeline Tracing" section later in this topic.

To use the Exchange Management Shell to configure the pipeline tracing sender address to capture messages from a specific SMTP address

  • Run the following command:

    Copy Code
    Set-TransportServer <Identity> -PipelineTracingSenderAddress <SMTPAddress>
    

    For example, to configure the SMTP address, chris@contoso.com, as the pipeline tracing sender address on the Server1 computer, run the following command:

    Copy Code
    Set-TransportServer Server1 -PipelineTracingSenderAddress chris@contoso.com
    

To use the Exchange Management Shell to configure the pipeline tracing sender address to capture messages generated by e-mail servers

  • Run the following command:

    Copy Code
    Set-TransportServer <Identity> -PipelineTracingSenderAddress "<>"
    

    For example, to configure <> as the pipeline tracing sender address on the Server2 computer, run the following command:

    Copy Code
    Set-TransportServer Server2 -PipelineTracingSenderAddress "<>"
    

For more information, see Using Pipeline Tracing to Diagnose Transport Agent Problems.

Configuring the Location of the Pipeline Tracing Log Directory

By default, the pipeline tracing log directory is located at C:\Program Files\Microsoft\Exchange Server\TransportRoles\Logs\PipelineTracing. The directory must be located on the Exchange 2007 computer.

To use the Exchange Management Shell to configure the pipeline tracing log location

  • Run the following command:

    Copy Code
    Set-TransportServer <Identity> -PipelineTracingPath <LocalFilePath>
    

    For example, to set the location of the pipeline tracing log directory to C:\Pipeline Tracing Logs, run the following command:

    Copy Code
    Set-TransportServer Server1 -PipelineTracingPath "C:\Pipeline Tracing Logs"
    

Enabling Pipeline Tracing

By default, pipeline tracing is disabled on computers that run Exchange 2007. You can enable or disable pipeline tracing on each Exchange server.

To use the Exchange Management Shell to enable pipeline tracing

  1. Configure the pipeline tracing sender address according to the "Configuring the Pipeline Tracing Sender Address" section earlier in this topic. You must configure the pipeline tracing sender address before you enable pipeline tracing.

  2. Run the following command to enable pipeline tracing:

    Copy Code
    Set-TransportServer <Identity> -PipelineTracingEnabled <$True | $False>
    

    For example, to enable pipeline tracing on the Server1 computer, run the following command:

    Copy Code
    Set-TransportServer Server1 -PipelineTracingEnabled $True
    

For detailed syntax and parameter information, see Set-TransportServer.