Event Policy File Archiving
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.
[edit event-options]
destinations {
destination-name {
archive-sites {
url <password password>;
}
transfer-delay seconds;
}
}
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:
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:
-
Configure the
uploadevent policy action, and specify the files to upload and the destination site.You can include multiple
uploadstatements, and thefilenamestatement can use filename globbing to specify multiple files.[edit event-options policy policy-name then] user@host# set upload filename (filename | committed) destination destination-name
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".
[edit event-options policy policy1 then] user@host# set upload filename committed destination mgmt-archives user@host# set upload filename /var/log/messages* destination mgmt-archives
- (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:
-
In the
execute-commandsevent policy action, configure a destination.[edit event-options policy policy-name then] user@host# set execute-commands destination destination-name
For example:
[edit event-options policy policy1 then] user@host# set execute-commands destination mgmt-archives
-
Define a descriptive string that will be included in the filename of the output file.
[edit event-options policy policy-name then] user@host# set execute-commands output-filename string
For example:
[edit event-options policy policy1 then] user@host# set execute-commands output-filename intf-info
- (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:
-
In the
event-scriptevent policy action, configure a destination.[edit event-options policy policy-name then] user@host# set event-script filename destination destination-name
For example:
[edit event-options policy policy1 then] user@host# set event-script get-intf-info destination mgmt-archives
-
Define a descriptive string that will be included in the filename of the output file.
[edit event-options policy policy-name then] user@host# set event-script filename output-filename string
For example:
[edit event-options policy policy1 then] user@host# set event-script get-intf-info output-filename intf-info
- (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:
hostname_YYYYMMDD_HHMMSS_output-filename_index-numberIn earlier releases, the filename has the following naming convention:
hostname_output-filename_YYYYMMDD_HHMMSS_index-numberThe 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.
Total transfer delay = transfer-delay (destination) + transfer-delay (event-policy-action)
To configure a transfer delay for a destination:
[edit event-options destinations destination-name] user@host# set transfer-delay seconds
For example, the following configuration sets a transfer delay of five seconds for the mgmt-archives destination.
[edit event-options destinations mgmt-archives] user@host# set transfer-delay 5
To configure a transfer delay for a specific event policy action:
-
In the appropriate event policy action hierarchy, configure the delay, in seconds.
[edit event-options policy policy-name then] user@host# set event-script filename destination destination-name transfer-delay seconds
[edit event-options policy policy-name then] user@host# set execute-commands destination destination-name transfer-delay seconds
[edit event-options policy policy-name then] user@host# set upload filename (filename | committed) destination destination-name transfer-delay seconds
For example:
[edit event-options policy policy1 then] user@host# set event-script get-intf-info.py destination mgmt-archives transfer-delay 5
[edit event-options policy policy2 then] user@host# set execute-commands destination mgmt-archives transfer-delay 7
[edit event-options policy policy3 then] user@host# set upload filename committed destination mgmt-archives transfer-delay 3
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.
[edit event-options]
policy policy1 {
events e1;
then {
execute-commands {
commands {
"show version";
}
output-filename command-output;
destination some-dest;
}
}
policy policy2 {
events e2;
then {
event-script bar.xsl {
output-filename event-script-output;
destination some-dest;
}
}
}
destinations {
some-dest {
transfer-delay 2;
archive-sites {
"scp://robot@my.big.com/foo/moo" password "$9$wisoGDjqfQnHqIclMN-HqmP5F"; ## SECRET-DATA
"scp://robot@my.little.com/foo/moo" password "$9$uova0RSrlMXNbKMDkPQ9CKM8Lxd"; ## SECRET-DATA
}
}
}
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:
retry-count number retry-interval seconds;
Where:
-
retry-count—Number of times the policy retries the upload operation if the upload fails. The default value for theretry-countstatement 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:
retry-count and
retry-interval statements for the event policy action's
destination statement.[edit event-options policy policy-name then] user@host# set event-script filename destination destination-name retry-count number retry-interval seconds
[edit event-options policy policy-name then] user@host# set execute-commands destination destination-name retry-count number retry-interval seconds
[edit event-options policy policy-name then] user@host# set upload filename (filename | committed) destination destination-name retry-count number retry-interval seconds
For example:
[edit event-options policy policy1 then] user@host# set event-script get-intf-info.py destination mgmt-archives retry-count 5 retry-interval 3
[edit event-options policy policy2 then] user@host# set execute-commands destination mgmt-archives retry-count 10 retry-interval 4
[edit event-options policy policy3 then] user@host# set upload filename committed destination mgmt-archives retry-count 2 retry-interval 10