Event Policy File Archiving
Configure event policies to upload files to predefined archive sites.
Event Policy File Archiving Overview
An event policy can archive files at the time an event occurs. You can then analyze the files to further diagnose events and troubleshoot network issues. Event policies can archive system files, including system log files, core files, and configuration files, from the time an event occurs. Additionally, some event policy actions can generate output files and then archive the files. When an event policy executes an event script or executes commands, it can write the output to a file and then archive the file.
To archive files from an event policy, you must first configure one or more destinations specifying the archive site 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 file archive operations. The transfer delay is 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. For some of these actions, you might want a transfer delay, and for other actions you might 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 might 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. 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> <routing-instance routing-instance-name>;
}
transfer-delay seconds;
}
}
For each destination, configure one or more archive site URIs, which are the sites to which the system attempts to upload the files. When you specify multiple archive sites for a given destination, the device transfers a file to the first archive site in the list, moving to the next site only if the previous transfer 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. If an archive site URI is reachable through a particular routing instance, you can configure the required routing instance in supported releases. Archive sites support using the management instance or a user-defined routing instance.
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. You can also specify a local device directory (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 optionally 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:
Configure the
execute-commandsevent policy action and specify the commands to execute.[edit event-options policy policy-name then] user@host# set execute-commands commands "command"
For example:
[edit event-options policy policy1 then] user@host# set execute-commands commands "show interfaces terse"
-
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 filename has the following naming convention:
hostname_YYYYMMDD_HHMMSS_output-filename_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 to subsequent files
to ensure the filename is 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. 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:
-
Configure the delay, in seconds, associated with the 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, both event policies, policy1 and
policy2, use the some-dest destination.
The destination uses a transfer delay of 2 seconds, which applies to the upload
operation 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://admin@example.com/home/admin/junos_archives" password "$ABC123"; ## SECRET-DATA
"scp://admin@example2.com/var/junos_archives" password "$ABC123"; ## 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 can 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 with the given set of archive sites for that destination if the transfer fails. The default value for theretry-countstatement is 0, and the maximum is 10. -
retry-interval—Number of seconds between each upload attempt.
For example, suppose you configure a destination with three archive sites and you
configure an event policy action with retry-count 3. When the
device uploads a file, it tries each archive site in turn until it successfully
transfers the file. If the device fails to connect to any archive site in the
list, it retries the archive site list three more times.
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
Change History Table
Feature support is determined by the platform and release you are using. Use Feature Explorer to determine if a feature is supported on your platform.