Help us improve your experience.

Let us know what you think.

Do you have time for a two-minute survey?

 
 

Event Policy File Archiving

SUMMARY Configure event policies to upload relevant files to predefined archive sites.

Event Policy File Archiving Overview

Various types of files are useful in diagnosing events and troubleshooting network issues. When an event policy action generates output files, you can archive the files for later analysis. Similarly, you might want to archive system files, including system log files, core files, and configuration files, from the time an event occurs.

When an event occurs, you can upload relevant files to a specified location for analysis. To archive files from an event policy, configure one or more destinations specifying the archive sites to which the files are uploaded. You then reference the configured destinations within event policies. When the event policy triggers, it uploads the files to the specified archive site.

You can configure a transfer delay for event policy archive operations. A transfer delay enables you to specify the number of seconds the event process (eventd) waits before uploading one or more files. A transfer delay helps ensure that a large file, such as a core file, is completely generated before the upload begins.

You can associate transfer delays with a destination and with an event policy action. If you associate a transfer delay with a destination, the transfer delay applies to all file upload actions that use that destination. You can also assign a transfer delay to an event policy action. For example, you might have multiple event policy actions that use the same destination, and for some of these event policy actions, you want a transfer delay, and for other event policy actions you want no transfer delay. If you configure a transfer delay for a destination, and you also configure a transfer delay for the event policy action, the resulting transfer delay is the sum of the two delays.

Transient network problems can cause a file upload operation to fail. If the upload fails for any reason, by default, the event policy does not retry the upload. However, you can configure an event policy to retry the file upload operation a specified number of times if the initial upload fails. You can also configure the time interval between each retry attempt.

Define Destinations for Event Policy File Archiving

When an event occurs, you can upload relevant files to a specified location for analysis. To archive files from an event policy, you must first configure one or more destinations specifying the archive sites to which the files are uploaded. You then reference the configured destinations within event policies.

To define a destination archive site, include the destinations statement at the [edit event-options] hierarchy level.

For each destination, configure one or more archive site URIs, which are the actual sites to which the files are uploaded. If you specify multiple archive site URIs for a given destination, the device attempts to transfer the files to the first archive site in the list and only uses subsequent archive sites if the transfer to the previous site fails. If an archive site requires authentication to log in, you can configure a plain-text password for that site. The device stores the password as an encrypted value in the configuration database.

The archive site URI is a file URI, an active or passive FTP URI, a Secure FTP (SFTP) URI, or a Secure Copy (SCP) URI. Local device directories are also supported (for example, /var/tmp). When you specify the archive site URI, do not add a forward slash (/) to the end of the URI.

  • file:<//host>/path

  • ftp://username@host:<port>url-path

  • pasvftp://username@host:<port>url-path

  • sftp://username@host:<port>url-path

  • scp://username@host:<port>url-path

  • <path>/<filename>

You can also define a transfer delay for each destination. The transfer delay is the number of seconds the event process (eventd) waits before uploading one or more files to that destination. A transfer delay helps to ensure that a large file, such as a core file, is completely generated before the upload begins.

To define a destination archive site to which event policies can upload files:

  1. Define the destination name, which is a user-defined identifier that is referenced by event policies.

    You can define multiple destinations with one or more archive sites.

    For example:

  2. Configure one or more archive site URIs.

    If an archive site requires authentication, configure the required plain-text password for that site.

    For example:

  3. (Optional) Configure the transfer delay, in seconds, associated with the destination.

    The following example configures a delay of five seconds for files uploaded to the mgmt-archives destination.

Configure an Event Policy to Upload Files

You can configure an event policy to upload existing system files or to upload the output files generated from an invoked event-script or operational command at the time an event occurs. The device uploads the files to the location referenced in the destination statement configured for that event policy action. You must specify a destination name that is configured at the [edit event-options destinations] hierarchy level.

The following examples configure various event policy actions to upload specific files to an existing destination. For each event policy, you must also configure the appropriate events and include any other required statements.

Upload System Files

To configure an event policy to upload system files to a configured destination:

  1. Configure the upload event policy action, and specify the files to upload and the destination site.

    You can include multiple upload statements, and the filename statement can use filename globbing to specify multiple files.

    The following event policy action uploads the committed configuration file and also uploads all files that are located in the /var/log directory and start with the string "messages".

  2. (Optional) Configure a transfer delay or the retry option as described in Configure a Delay Before Files Are Uploaded and Configure an Event Policy to Retry the File Upload Action

Upload Command Output Files

An event policy can include the execute-commands event policy action to execute commands in response to an event and write the command output to a file. To configure an event policy to upload the command output file to a configured destination:

  1. In the execute-commands event policy action, configure a destination.

    For example:

  2. Define a descriptive string that will be included in the filename of the output file.

    For example:

  3. (Optional) Configure a transfer delay or the retry option as described in Configure a Delay Before Files Are Uploaded and Configure an Event Policy to Retry the File Upload Action

Upload Event Script Output Files

When an event policy executes an event script in response to an event, the event script can write output to a file. To configure an event policy to upload the generated output file to a configured destination:

  1. In the event-script event policy action, configure a destination.

    For example:

  2. Define a descriptive string that will be included in the filename of the output file.

    For example:

  3. (Optional) Configure a transfer delay or the retry option as described in Configure a Delay Before Files Are Uploaded and Configure an Event Policy to Retry the File Upload Action

Filenames for Uploaded Files

When an event policy action uploads files, the filename for each uploaded file includes the hostname and timestamp to ensure that it is unique. The name of the file depends on the Junos OS software version. Starting in Junos OS Release 14.1R3, the filename has the following naming convention:

In earlier releases, the filename has the following naming convention:

The output-filename string is either the name of an existing file or the value of the output-filename statement configured for that event policy action. If a device triggers an event policy multiple times in a 1-second period, it appends an index number is to each filename to ensure that the filenames are still unique. The index number range is 001 through 999.

For example, suppose you have an event policy action with output-filename configured as rpd-messages on device r1 running Junos OS Release 21.1R1. If the event policy triggers 3 times in 1 second, the filenames would be similar to the following:

  • r1_20210623_132333_rpd-messages

  • r1_20210623_132333_rpd-messages_001

  • r1_20210623_132333_rpd-messages_002

Configure a Delay Before Files Are Uploaded

You can configure an event policy to upload existing system files or to upload the output files generated from an invoked event-script or operational command at the time an event occurs. For event policy upload operations, you can configure a transfer delay to specify the number of seconds the event process (eventd) waits before uploading one or more files. By configuring a transfer delay, you can better ensure that a large file, such as a core file, is completely generated before the upload begins.

You can associate transfer delays with a destination and with an event policy action. If you associate a transfer delay with a destination, the transfer delay applies to all file upload actions that use that destination. You can also assign a transfer delay to an event policy action. For example, you might have multiple event policy actions that use the same destination, and for some of these event policy actions, you want a transfer delay, and for other event policy actions you want no transfer delay.

If you configure a transfer delay for a destination at the [edit event-options destinations destination-name] hierarchy level and you also configure a transfer delay for the event policy action, the resulting transfer delay is the sum of the two delays.

To configure a transfer delay for a destination:

Configure the delay, in seconds, associated with the destination.

For example, the following configuration sets a transfer delay of five seconds for the mgmt-archives destination.

To configure a transfer delay for a specific event policy action:

  1. In the appropriate event policy action hierarchy, configure the delay, in seconds.

    For example:

In the following example, the some-dest destination is common for both event policies, policy1 and policy2. A transfer delay of 2 seconds is associated with the some-dest destination and applies to uploading the output files to the destination for both event policies.

Configure an Event Policy to Retry the File Upload Action

You can configure an event policy to upload existing system files or to upload the output files generated from an invoked event-script or operational command at the time an event occurs. Transient network problems can cause a file upload operation to fail. If the upload fails for any reason, by default, the event policy does not retry the upload. However, you can configure an event policy to retry a file upload operation.

You configure the file upload retry option for a given event policy action. To configure the retry option, include the retry-count and retry-interval statements:

Where:

  • retry-count—Number of times the policy retries the upload operation if the upload fails. The default value for the retry-count statement is 0, and the maximum is 10.

  • retry-interval—Number of seconds between each upload attempt.

To configure the event policy to retry a file upload operation for a given event policy action:

Include the retry-count and retry-interval statements for the event policy action's destination statement.

For example: