Sending messages in policy via Syslog

Products

• STARTER PACK-7
• CA Rapid App Security
• CA API Gateway

Issue/Introduction

Solution

Background

The Layer 7 Gateway has supported transmitting log files and audit records via Syslog for a significant amount of time. The Gateway can be configured (via the Layer 7 Policy Manager) to route certain classes of data (audit records, specific services or policies, or core Gateway log files) to Syslog recipients via the Manage Log/Audit Sinks functionality. This allows a Syslog recipient to receive all log entries from a particular type of data from the examples given previously. In certain circumstances, it may be desired to log a specific Syslog message when consuming a published service policy. This can be accomplished by utilizing a custom Syslog Log Sink and leveraging the Add Audit Details assertion in a published service policy or internal audit sink policy.

Implementation

The ability to log a specific message to a Syslog server requires three steps:

1. Insert the "Add Audit Details" assertion into your published service policy.
2. Create a Log Sink routing to a Syslog recipient.
3. Configure a Log Sink to filter on a specific package.

The Add Audit Details assertion has several important items that must be configured properly:

1. Configure the desired Syslog message in the "Message" field.
2. Set the "Category" to "Log"
3. Enable the "Custom logger name" check box.
4. Set the custom logger name as desired.
5. Set the appropriate Java log level as desired.

<Please see attached file for image>

After configuring the assertion to build the desired message and assign it to a particular logging class, you'll need to configure a Log Sink to transmit messages via Syslog. Open the "Manage Log/Audit Sinks" task and create a new Log Sink. The following dialog will be opened. You will need to configure the following items:

1. The name of the log sink.
2. The description of the log sink
3. Set the "Enabled" check box.
4. Set the "Type" to "Syslog"
5. Set the "Severity Threshold" to "All"
6. Add a Filter of type 'Category/Gateway Log'
7. Add the appropriate package name to the "Filters" field.

Note that the example filter below matches the custom logger name specified in the previous step

<Please see attached file for image>

After initially creating the log sink and configuring the information to transmit, you must configure the Gateway to send the sink to a particular Syslog recipient by doing the following:

1. Set the "Protocol"
2. Set the "Host"
3. Set the "Facility"
4. Optionally enable logging the Gateway host name with the message
5. Set the "Format"
6. Set the "Character Set"
7. Set the "Timezone"

Note: Most of these configuration items will be heavily dependent upon your Syslog implementation. Please consult with a system administrator responsible for the Syslog implementation in your organization for more assistance with the required configuration of these fields.

<Please see attached file for image>

The settings can be verified with the "Send a Test Message" button. For the test message?to work however, the 'Category=Gateway Log' filter needs to be in place.?If properly configured, the Gateway will send a sample Syslog message to the configured recipient. If active, the Syslog recipient should display a log entry in accordance with its local rules. You may need to consult with a Syslog administrator in your organization to determine where this data can be accessed as implementations vary by organization.

The screen capture below shows a simple example implementation of this process. A Log Sink for the custom logger "yourLogger" has been configured in advance. The published service policy will attempt to gather HTTP Basic credentials and authenticate them against an identity provider. If that authentication succeeds then a request is routed to a particular HTTP server. If that authentication fails then an audit detail is generated with the specified message. That audit detail will be sent to the "yourLogger" logger. The Gateway will capture that log message and transmit it via the Log Sink configured previously.

<Please see attached file for image>

Environment

Release:
Component: APIGTW