5.12. Log Command Reference

This command creates a text description stored in the configuration file for a configuration context.

The command associates a text string with a configuration context to help identify the content in the configuration file.

The no form of the command removes the string from the configuration.

This command administratively disables an entity. When disabled, an entity does not change, reset, or remove any configuration settings or statistics.

The operational state of the entity is disabled as well as the operational state of any entities contained within. Many objects must be shut down before they can be deleted.

The no form of this command administratively enables an entity.

This command creates an access or network accounting policy. An accounting policy defines the accounting records that are created.

Access accounting policies are policies that can be applied to one or more service access points (SAPs). Changes made to an existing policy, using any of the sub-commands, are applied immediately to all SAPs where this policy is applied.

Network accounting policies are policies that can be applied to one or more network ports. Changes made to an existing policy, using any of the sub-commands, are applied immediately to all network ports where this policy is applied.

If an accounting policy is not specified on a SAP or network port, accounting records are produced in accordance with the access or network policy designated as the default. For more information, see the default command.

The no form of the command deletes the policy from the configuration. The accounting policy cannot be deleted unless it is removed from all the SAPs or network ports where the policy is applied. Use the show>log>accounting-policy command to see where an accounting policy is used and which accounting policy is the default policy.

This command configures the interval between collection of accounting records.

This command configures the accounting policy specified by acct-policy-id to be the default accounting policy that is used by all SAPs or network ports that do not have a specified accounting policy.

For a SAP or network port, if no accounting policy is explicitly specified and a default policy is defined, records are produced as per the default accounting policy. If no default policy is defined, no records are collected. However, if an accounting policy is explicitly defined for a SAP or network port, records are collected for that SAP or network port.

Only one access accounting policy ID can be designated as the default access policy. Similarly, only one network accounting policy ID can be designated as the default network accounting policy.

The record-name must be specified prior to configuring an accounting policy as default.

If a policy is configured as the default policy, a no default command must be issued before a new default policy can be configured.

Default accounting policies cannot be explicitly applied. For example, if default is set for accounting-policy 10, policy 10 cannot be assigned.

The no form of the command removes the default pol icy designation from the policy ID. The accounting policy is removed from all SAPs or network ports that do not have a policy explicitly defined. If there is no policy defined as the default policy, no accounting policy is applied to those entities.

This command adds the record name to the accounting policy, specifying which records to forward to the configured accounting file (identified by log-file-id). Each accounting policy can only contain one record name. To obtain a list of all record types that can be configured, use the show>log>accounting-records command.

The record-name must be specified prior to configuring an accounting policy as default.

To configure an accounting policy for access ports, select a service record (for example, service-ingress-octets). To change the service record to another service record, re-enter the record command with the new record-name to replace the old record-name.

When configuring an accounting policy for network ports, select a network record. To change the network record to another network record, re-enter the record command with the new record-name to replace the old record-name.

Only one record may be configured in a single accounting policy. If changing the record switches it from network to service, or from service to network, the old record-name must be removed using the no form of this command. For example, to change an accounting policy configuration from a network-egress-octets record to a service-ingress-octets record, use the no record command and then enter the service-ingress-octets record.

Note: Collecting excessive statistics can adversely affect CPU usage and take up large amounts of storage space.

The no form of the command removes the record from the policy.

This command specifies the destination for the accounting records selected for the accounting policy.

This command is used to specify that a particular event, or all events associated with an application, are either generated or suppressed.

Events are generated by an application and contain an event number and description explaining the cause of the event. Each event has a default designation that directs it to be generated or suppressed.

Events are generated with a default severity level that can be modified by using the severity-level option. For example, to change event reporting for an external alarm output on the chassis, do the following:

Events that are suppressed by default are typically used for debugging purposes. Events are suppressed at the time the application requests the event’s generation. No event log entry is generated regardless of the destination. While this feature can save processor resources, there may be a negative effect on the ability to troubleshoot problems if the logging entries are not generated. However, the generation of too many events may cause excessive overhead.

The throttle parameter enables event throttling for these events. The throttling rate is set globally for all events with the throttle-rate command. The throttling rate can also be configured independently for each log event by using the specific-throttle-rate parameter; this rate overrides the globally configured throttle rate for the specified log event.

The no form of the command resets the parameters to the default setting for events for the application or a specific event within the application. The severity-level, generate, and suppress options will also be reset to the initial values.

This command configures an event throttling rate.

This command enables the context to configure event handling in the Event Handler System (EHS).

This command configures an event handler.

The no form of the command removes the specified event handler.

This command enables the context to configure the event handler action list.

This command configures an event handler action-list entry. An action list consists of one or more entries. Each entry in the list references a configured script policy, which in turn references a configured script.

Multiple entries can be configured in the action list if multiple actions are required when an event triggers the event handler; for example, an event trigger results in the execution of different scripts. When the handler is triggered, it runs through the entries in sequence.

The no form of the command removes the specified action-list entry.

This command specifies the minimum delay between subsequent executions of the action specified in this entry. This is useful, for example, to ensure that a script does not get triggered to execute too often.

This command specifies the script policy to use for this event handler action-list entry. The associated script is launched when the handler is triggered.

The script policy must already have been configured under the config>system>script-control context.

This command enables the context to configure log events as triggers for event handlers in EHS.

This command defines a specific log event that triggers the associated event handler. Further matching criteria can be applied (with the log-filter command) to only trigger certain handlers with certain instances of the log event.

The log event consists of an application ID and event ID.

The no form of the command removes the specified log event.

This command configures a trigger entry for the specified log event. A trigger entry references a previously configured event handler. One or more trigger entries can be configured for the event.

Trigger entries can also be configured with a previously configured log filter.

The no form of the command removes the specified trigger entry.

This command configures how many times the specified log event occurs before an action is triggered (for example, an EHS script). The number of occurrences of the event can be optionally bounded by a time window. If no time window is specified, the action is triggered every specified Nth event.

Triggering occurs at the specified Nth event, not at the end of the time window.

This command specifies the event handler to be used for this trigger entry. The event handler must have already been configured under the config>log>event-handling>handler context.

If the log event occurs and matches the criteria configured in the log filter (see log-filter), the event handler is triggered. When the event handler is triggered, the script that is referenced by the script policy that is in turn referenced by the event handler, is executed.

This command specifies the log filter to be used for this trigger entry. The log filter must have already been configured under the config>log>filter context.

The log filter defines the matching criteria that must be met in order for the log event to trigger the event handler. The log filter is applied to the log event, and if the filtering decision results in a forward action, the event handler is triggered.

This command enables the context to configure a file ID template that is used as a destination for an event log or an accounting (billing) file.

The template defines the file location and characteristics of the destination for a log event message stream or for accounting and billing information. The log-file-id variable defined in this context is subsequently specified in the to command under config>log>log-id or config>log>accounting-policy contexts, to direct specific logging or accounting source streams to the file destination.

A file ID can only be assigned to either one log-id or one accounting-policy. It cannot be reused for multiple instances. A file ID and associated file definition must exist for each log and accounting file that will be stored in the file system.

A file is created when the file ID defined by this command is selected as the destination type for a specific log or accounting record. Log files are collected in a “log” directory. Accounting files are collected in an “act” directory.

The filenames for a log or accounting file are created by the system (see Table 38).

where:

The accounting file is compressed and has a .gz extension

When initialized, each file will contain:

If the process of writing to a log file fails (for example, the compact flash card is full), the log file will not become operational even if the compact flash card is replaced. Enter a clear log command or a shutdown/no shutdown command sequence to reinitialize the file.

If the location fails (for example, the compact flash card fills up during the write process), a trap is sent.

The no form of the command removes the file ID from the configuration. A file ID can only be removed from the configuration if the file is not the designated output for a log destination. The actual file remains on the file system.

This command specifies the location where the log or accounting billing file will be created.

The location command is optional. If the location command is not explicitly configured, log and accounting files will be created on cf3: for the following:

For the 7705 SAR-18, log files are created by default on cf1: and accounting files are created by default on cf2:. There are no overflows onto other devices.

Note: The 7705 SAR-A, 7705 SAR-Ax, 7705 SAR-W, 7705 SAR-Wx, 7705 SAR-Hc, and 7705 SAR-X do not have field-replaceable compact flash drives; they are shipped with integrated flash memory that is used to store system boot software, OS software, and configuration files and logs. The flash memory is identified as cf3-A: by the system. On the 7705 SAR-X and 7705 SAR-Ax, the flash memory is 512 Mbytes; for the other platforms, the flash memory is 256 Mbytes.

When multiple location commands are entered in a single file ID context, the last command overwrites the previous command.

When the location of a file ID that is associated with an active log ID is changed, the log events are not immediately written to the new location. The new location does not take effect until the log rolls over, either because the rollover period has expired or a clear>log log-id command is entered to manually roll over the log file.

When creating log or accounting files, the designated location is used as long as there is available space. If no space is available, an attempt is made to delete unnecessary files that are past their retention date.

If sufficient space is not available, an attempt is made to remove the oldest to newest closed log or accounting files. After each file is deleted, the system attempts to create the new file.

A medium severity trap is issued to indicate that the compact flash is either not available or that no space is available on the specified flash.

A high-priority alarm condition is raised if the compact flash device for this file ID is not present or if there is insufficient space available. If space does becomes available, the alarm condition will be cleared.

Use the no form of this command to revert to default settings.

This command configures how often an event or accounting log is rolled over or partitioned into a new file.

An event or accounting log is actually composed of multiple individual files. The system creates a new file for the log based on the rollover time, expressed in minutes.

The retention option, expressed in hours, allows you to modify the default time that the file is kept in the system. The retention time is based on the rollover time of the file. The retention time is used as a factor to determine which files should be deleted first as the file space becomes full.

When multiple rollover commands for a file ID are entered, the last command overwrites the previous command.

This command creates a context for an event filter. An event filter specifies whether to forward or drop an event or trap based on the match criteria.

Filters are configured in the filter filter-id context and then applied to a log in the log-id log-id context. Only events for the configured log source streams destined for the log ID where the filter is applied are filtered.

Any changes made to an existing filter, using any of the sub-commands, are immediately applied to the destinations where the filter is applied.

The no form of the command removes the filter association from log IDs, which causes those logs to forward all events.

The default action specifies the action that is applied to events when no action is specified in the event filter entries or when an event does not match the specified criteria.

When multiple default-action commands are entered, the last command overwrites the previous command.

The no form of the command reverts to the default value.

This command is used to create or edit an event filter entry. Multiple entries may be created using unique entry-id numbers. The -TiMOS implementation exits the filter on the first match found and executes the action in accordance with the action command.

Comparisons are performed in an ascending entry ID order. When entries are created, they should be arranged sequentially from the most explicit entry to the least explicit. Matching ceases when a packet matches an entry. The entry action is performed on the packet, either drop or forward. To be considered a match, the packet must meet all the conditions defined in the entry.

An entry may have no match criteria defined (in which case, everything matches) but must have at least the action keyword for it to be considered complete. Entries without the action keyword will be considered incomplete and rendered inactive.

The no form of the command removes the specified entry from the event filter. Entries removed from the event filter are immediately removed from all log IDs where the filter is applied.

This command specifies a drop or forward action associated with the filter entry.

If neither drop nor forward is specified, the default-action will be used for traffic that conforms to the match criteria. This could be considered a No-Op filter entry used to explicitly exit a set of filter entries without modifying previous actions.

When multiple action commands are entered, the last command will overwrite the previous command.

The no form of the command removes the specified action statement.

This command enables the context to enter or edit match criteria for a filter entry. When the match criteria is satisfied, the action associated with the entry is executed.

If more than one match parameter (within one match statement) is specified, then all the criteria must be satisfied and functional before the action associated with the match is executed.

Use the applications command to display a list of the valid applications.

Match context can consist of multiple match parameters (application, event-number, severity, subject), but multiple match statements cannot be entered per entry.

The no form of the command removes the match criteria for the entry-id.

This command adds a TiMOS application as an event filter match criterion.

A TiMOS application is the software entity that reports the event. Examples of applications include: IP, MPLS, CLI, and SERVICES. Only one application can be specified per entry.

When multiple application commands are entered, the last command will overwrite the previous command.

The no form of the command removes the application as a match criterion.

This command adds system messages as a match criterion.

The no form of the command removes system messages as a match criterion.

This command adds a TiMOS application event number as a match criterion.

TiMOS event numbers uniquely identify a specific logging event within an application.

Only one number command can be entered per event filter entry. If multiple number commands are entered, the last command overwrites the previous command.

The no form of the command removes the event number as a match criterion.

This command specifies the log event matches for the router.

This command adds an event severity level as a match criterion.

Only one severity command can be entered per event filter entry. When multiple severity commands are entered, the last command overwrites the previous command.

The no form of the command removes the severity match criterion.

This command adds an event subject as a match criterion.

The subject is the entity for which the event is reported, such as a port. In this case, the port-id string would be the subject.

Only one subject command can be entered per event filter entry. If multiple subject commands are entered, the last command overwrites the previous command.

The no form of the command removes the subject match criterion.

This command enables the context to configure a syslog target host that is capable of receiving selected syslog messages from the 7705 SAR.

A valid syslog-id must have the target syslog host address configured.

A maximum of 10 syslog IDs can be configured.

No log events are sent to a syslog target address until the syslog-id has been configured as the log destination (to) in the log-id node.

This command associates the syslog target host IP address with the syslog ID.

This parameter is mandatory. If no address is configured, syslog data cannot be forwarded to the syslog target host.

Only one address can be associated with a syslog-id. If multiple addresses are entered, the last address entered overwrites the previous address.

The same syslog target host can be used by multiple log IDs.

The no form of the command removes the syslog target host IP address.

This command configures the facility code for messages sent to the syslog target host.

Multiple syslog IDs can be created with the same target host but each syslog ID can only have one facility code. If multiple facility codes are entered, the last facility code entered overwrites the previous facility code.

If multiple facilities need to be generated for a single syslog target host, then multiple log-id entries must be created, each with its own filter criteria to select the events to be sent to the syslog target host with a given facility code.

The no form of the command reverts to the default value.

This command configures the syslog message severity level threshold. All messages with a severity level equal to or higher than the threshold are sent to the syslog target host.

Only a single threshold level can be specified. If multiple level commands are entered, the last command will overwrite the previous command.

The no form of the command reverts to the default value.

This command adds the string prepended to every syslog message sent to the syslog host.

RFC 3164, The BSD syslog Protocol, allows an alphanumeric string (tag) to be prepended to the content of every log message sent to the syslog host. This alphanumeric string can, for example, be used to identify the node that generates the log entry. The software appends a colon (:) and a space to the string and it is inserted in the syslog message after the date stamp and before the syslog message content.

Only one string can be entered. If multiple strings are entered, the last string overwrites the previous string. The alphanumeric string can contain lowercase (a-z), uppercase (A-Z) and numeric (0-9) characters.

The no form of the command removes the log prefix string.

This command configures the UDP port that will be used to send syslog messages to the syslog target host.

The port configuration is needed if the syslog target host uses a port other than the standard UDP syslog port 514.

Only one port can be configured. If multiple port commands are entered, the last entered port overwrites the previously entered ports.

The no form of the command reverts to default value.

This command creates a context to configure destinations for event streams.

The log-id context is used to direct events, alarms, traps, and debug information to respective destinations.

A maximum of 100 logs can be configured.

Before an event can be associated with this log-id, the log-id>from command identifying the source of the event must be configured.

Only one destination can be specified for a log-id. The destination of an event stream can be an in-memory buffer, console, session, snmp-trap-group, syslog, or file.

Use the event-control command to suppress the generation of events, alarms, and traps for all log destinations.

An event filter policy can be applied in the log-id context to limit which events, alarms, and traps are sent to the specified log-id.

Log-IDs 99 and 100 are created by the agent. Log-ID 99 captures all log messages. Log-ID 100 captures log messages with a severity level of major and above.

The no form of the command deletes the log destination ID from the configuration.

This command associates an event filter policy with the log destination.

The filter command is optional. If no event filter is configured, all events, alarms and traps generated by the source stream will be forwarded to the destination.

An event filter policy defines (limits) the events that are forwarded to the destination configured in the log-id. The event filter policy can also be used to select the alarms and traps to be forwarded to a destination snmp-trap-group.

The application of filters for debug messages is limited to application and subject only.

Accounting records cannot be filtered using the filter command.

Only one filter-id can be configured per log destination.

The no form of the command removes the specified event filter from the log-id.

This command selects the source stream to be sent to a log destination.

One or more source streams must be specified. The source of the data stream must be identified using the from command before you can configure the destination using the to command. The from command can identify multiple source streams in a single statement (for example: from main change debug-trace).

Only one from command may be entered for a single log-id. If multiple from commands are entered, then the last command entered overwrites the previous command.

The no form of the command removes all previously configured source streams.

This command instructs the events selected for the log ID to be directed to the console. If the console is not connected, all entries are dropped.

The command is one of the to commands used to specify the log ID destination. A to command is mandatory when configuring a log destination.

The source of the data stream must be specified in the from command prior to configuring the destination with the to command.

The to command can only be set once. It cannot be modified or re-entered. If the log destination needs to be changed or if the maximum size of an SNMP log or memory log needs to be modified, the log ID must be removed and then recreated.

This command instructs the events selected for the log ID to be directed to a specified file.

The command is one of the to commands used to specify the log ID destination. A to command is mandatory when configuring a log destination.

The source of the data stream must be specified in the from command prior to configuring the destination with the to command.

The to command can only be set once. It cannot be modified or re-entered. If the log destination needs to be changed or if the maximum size of an SNMP log or memory log needs to be modified, the log ID must be removed and then recreated.

This command instructs the events selected for the log ID to be directed to a memory file. A memory file is a circular buffer. Once the file is full, each new entry replaces the oldest entry in the log.

The command is one of the to commands used to specify the log ID destination. A to command is mandatory when configuring a log destination.

The source of the data stream must be specified in the from command prior to configuring the destination with the to command.

The to command can only be set once. It cannot be modified or re-entered. If the log destination needs to be changed or if the maximum size of an SNMP log or memory log needs to be modified, the log ID must be removed and then recreated.

This command instructs the events selected for the log ID to be directed to the current console or Telnet session. This command is only valid for the duration of the session. When the session is terminated, the to session configuration is removed. A log ID with a session destination is saved in the configuration file but the to session part of the configuration is not stored.

The command is one of the to commands used to specify the log ID destination. A to command is mandatory when configuring a log destination.

The source of the data stream must be specified in the from command prior to configuring the destination with the to command.

The to command can only be set once. It cannot be modified or re-entered. If the log destination needs to be changed or if the maximum size of an SNMP log or memory log needs to be modified, the log ID must be removed and then recreated.

This command instructs the alarms and traps to be directed to the snmp-trap-group associated with the log-id.

A local circular memory log is always maintained for SNMP notifications sent to the specified snmp-trap-group for the log-id.

The command is one of the to commands used to specify the log ID destination. A to command is mandatory when configuring a log destination.

The source of the data stream must be specified in the from command prior to configuring the destination with the to command.

The to command can only be set once. It cannot be modified or re-entered. If the log destination needs to be changed or if the maximum size of an SNMP log or memory log needs to be modified, the log ID must be removed and then recreated.

This command instructs the alarms and traps to be directed to a specified syslog. To remain consistent with the standards governing syslog, messages to syslog are truncated to 1 kbyte.

The command is one of the to commands used to specify the log ID destination. A to command is mandatory when configuring a log destination.

The source of the data stream must be specified in the from command prior to configuring the destination with the to command.

The to command can only be set once. It cannot be modified or re-entered. If the log destination needs to be changed or if the maximum size of an SNMP log or memory log needs to be modified, the log ID must be removed and then recreated.

This command specifies whether the time should be displayed in local or Coordinated Universal Time (UTC) format.

This command enables the context to configure a group of SNMP trap receivers and their operational parameters for a given log-id.

A trap group specifies the types of SNMP traps and specifies the log ID that will receive the group of SNMP traps. A trap group must be configured in order for SNMP traps to be sent.

To suppress the generation of all alarms and traps, see the event-control command. To suppress alarms and traps that are sent to this log-id, see the filter (log destination) command. Once alarms and traps are generated, they can be directed to one or more SNMP trap groups. Logger events that can be forwarded as SNMP traps are always defined on the main event source.

The no form of the command deletes the SNMP trap group.

This command adds or modifies a trap receiver and configures the operational parameters for the trap receiver. A trap reports significant events that occur on a 7705 SAR, such as errors or failures.

Before an SNMP trap can be issued to a trap receiver, the to console, snmp-trap-group, and at least one trap-target must be configured.

The trap-target command is used to add or remove a trap receiver from an snmp-trap-group. The operational parameters specified in the command include:

A single snmp-trap-group log-id can have multiple trap receivers. Each trap receiver can have different operational parameters.

An address can be configured as a trap receiver more than once as long as a different port is used for each instance.

To prevent resource limitations, only configure a maximum of 10 trap receivers.

Note: If the same trap-target name port port parameter value is specified in more than one SNMP trap group, each trap destination should be configured with a different notify-community value. This allows a trap receiving an application, such as NMS, to reconcile a separate event sequence number stream for each 7705 SAR event log when multiple event logs are directed to the same IP address and port destination.

The no form of the command removes the SNMP trap receiver from the SNMP trap group.