Applies To:

Show Versions Show Versions

Manual Chapter: ARX API and Notification Rules
Manual Chapter
Table of Contents   |   << Previous Chapter   |   Next Chapter >>

34 
The ARX supports a SOAP-based API for monitoring general configuration, usage statistics, and specific file and directory changes in its managed volumes. You can use the show statistics api command to show the usage statistics for this API. This command, clear statistics api, resets all of the statistical counters to 0 (zero).
The show statistics api command shows cumulative statistics for API usage. Use this command to clear those statistical counters.
provA# clear statistics api
A notification rule is required to support the SOAP-based API for its managed volume. This rule takes regular snapshots, or point-in-time copies, of a volumes files and metadata. These are called notification snapshots, and managed volumes keep statistics on them. Use this command to clear the cumulative statistics for a particular notification rule.
clear statistics notification namespace volume notification-rule
namespace (1-30 characters) identifies a namespace.
volume (1-1024 characters) is a volume that supports notification snapshots.
notification-rule (1-1024 characters) is the rule whose statistics should be cleared.
The show policy ... details command shows cumulative statistics for notification-snapshot operations. Use this command to clear the statistical counters for one notification rule.
provA# clear statistics notification provMed /mds mdChgs
A notification rule is required to support a SOAP-based API for the current volume. This rule takes regular snapshots, or point-in-time copies, of the volumes files and metadata. The volume can use these snapshots to answer procedure calls from the APIs clients.
Use the enable command to enable the current notification rule. The rule must be enabled to create any ARX snapshots, either manually or by a schedule. It also must be enabled to track file changes in real time.
Use no enable to disable the current notification rule.
Use the no form of the command to remove the notification rule without removing any of the snapshots behind it.
name (1-1024 characters) is a name you choose for the notification rule.
The ARX volume creates a notification snapshot by issuing CLI commands to each of its back-end filers, including the filer used for the metadata share. The ARX therefore needs information and credentials for accessing each filers CLI. From gbl-filer mode, use the filer-type command to identify the filer vendor, use proxy-user (gbl-filer) to identify a proxy user with proper management-login credentials, and use manage snapshots to declare that the filer supports snapshots. You can use the ip address ... management command to designate the management-IP address at that station (by default, the ARX logs into the CLI through an external filers primary-IP address, set with the simplest syntax for the ip address command).
Note: All of the filers behind the managed volume, including the one that contains the volumes metadata share, must support snapshots. The notification rule requires a full set of snapshots so that it can support specific API queries about any file in the volume. This rule does not support sparse snapshots, where some back-end shares are excluded. Configure all of the volumes external filers as described above.
When you create a new notification rule, the CLI prompts for confirmation. Enter yes to create the rule. (You can use terminal expert to eliminate confirmation prompts for creating new policy objects.)
This command places you in gbl-ns-vol-ntfy mode, where you enable the rule and where you have some options that you can apply to it. By default, a notification rule retains three snapshots; whenever it successfully creates a new snapshot, it deletes the oldest snapshot so that there are never more than three. You can use the optional retain (gbl-ns-vol-ntfy) command to change the number of retained snapshots. A notification rule requires a regular schedule, which you set with the schedule (gbl-ns-vol-ntfy) command. To enable report-generation for each snapshot, use the report (gbl-ns-vol-ntfy) command. You must use the enable (gbl-ns-vol-ntfy) command enable this rule to take any snapshots at all, even manually. You cannot exclude any storage shares in the managed volume; a notification rule requires that all storage shares in the volume support snapshots. The snapshots automatically exclude any shares with the special replica-snap setting.
To activate the ARX API, use the management access [http-api | https-api] command followed by the permit command. This opens a port where a SOAP client can send queries to this volume. The HTTP-API port is 83, and the HTTPS-API port is 843.
http://arx-management-ip:83/arx-api/
where arx-management-ip is either the out-of-band management-IP address (interface mgmt) or an in-band (VLAN) management-ip address (interface vlan). The permit command determines which of these address types are available for access. Use show interface mgmt and/or show interface vlan to find the IP addresses for each interface.
https://arx-management-ip:843/arx-api/
where arx-management-ip is a valid management IP, as described above.
You can use the show statistics api command to find usage statistics for the API.
You can use snapshot manage to incorporate existing filer snapshots into the notification rule, but you cannot use it for any metadata snapshots. The command is therefore not recommended for notification rules.
Each ARX snapshot has one or more component snapshots on its back-end filers. You can use the snapshot verify command to verify that all of the component snapshots still exist behind a notification rule. This does not check the snapshot on the metadata share.
For sites where these queries are particularly important, you can use the snapshot consistency command to put up a VIP fence for snapshots. This fence prevents client access to any VIP that supports this volume. This may affect multiple volumes. The fence stays up until the last filer completes its snapshot or checkpoint, or until a timeout expires.
By default, CIFS clients can access their snapshots with Windows Explorer. They select a file or directory, pull up its Properties, and find a list of snapshots for the file or directory in the Previous Versions tab. CIFS clients can use this interface to find and restore previous versions of their files and directories. Microsoft calls this the Volume Shadowing Service, or VSS, for Shared Folders.
Refer to the Guidelines for the snapshot rule command to learn about CLI commands that can affect the client view of snapshots.
acopia_id_time-stamp_uuid_filer-volume
id is an integer that the snapshot software uses internally.
time-stamp is in yyyymmddHHMM format. This is the time that the snapshot was created.
uuid is the Universally-Unique ID that identifies the ARX. In a redundant pair, this is the UUID for the peer that was originally configured as senior/active, no matter which peer is currently active. You can find an ARXs UUID in the output of show running-config.
filer-volume is the name of the filers volume.
The no form of the command removes the rule without removing any snapshots from the back-end filers. To remove the snapshots from the filers, use the snapshot remove command before you remove the rule. This is an efficient method for cleaning all of the supporting snapshots behind the rule. If supporting snapshots remain when you invoke no notification rule, the CLI lists all remaining snapshots when it prompts for confirmation.
The snapshot remove command removes snapshots from all the storage-share filers; you must manually remove snapshots from your metadata-share filer.
provA(gbl-ns-vol[provMed~/mds])# notification rule mdChgs
ip address ... management
A notification rule is required to support a SOAP-based API for the current volume. Use this command to enable progress reports for the current notification rule.
Use no report to prevent progress reports.
report file-prefix
file-prefix (1-1024 characters) sets a prefix for all notification reports. Each report has a unique name in the following format:
file-prefix_0_create_YearMonthDayHourMinuteSecondsMilliseconds.rpt
Use show reports for a list of reports, or show reports file-name to show the contents of one report.
See Figure 34.1 on page 34-11 for a sample snapshot-create report.
provA# show reports md_chgs_0_create_20120307023703404.rpt
A notification rule is required to support a SOAP-based API for the current volume. Each notification rule retains some maximum number of snapshots, or point-in-time copies, of its volumes files and metadata. Use this command to set the number of retained snapshots for the current rule.
Use no retain to revert to the default retention count.
retain snap-count
snap-count (1-1024) is the maximum number of snapshots for this rule to retain.
A notification rule is required to support a SOAP-based API for the current volume. Use this schedule command to assign a schedule to the current notification rule.
Use no schedule to remove the rules schedule.
name (1-64 characters) identifies the schedule. Use show schedule for a list of configured schedules.
A notification rule takes snapshots (point-in-time copies) of an ARX volume on a regular schedule. This command determines which schedule to use.
If more than one snapshot-producing rule (snapshot rule, snapshot replica-snap-rule, and/or notification rule) uses the same schedule, the ARX aggregates all of the filer snapshots at once. This is called snapshot grouping. By grouping the filer snapshots, the ARX avoids any duplicate snapshots on a given back-end volume.
A notification rule is required to support a SOAP-based API for the current volume. Use the show notification command to see the current status of one or more notification rules.
show notification namespace ns volume path rule rule-name
ns (1-30 characters) identifies the namespace with the notification rule(s).
path (1-1024 characters) focuses on one volume in the namespace.
rule-name (1-1024 characters) focuses on one notification rule. This changes the output to a detailed view of the rule.
The simplest output shows a summary of all selected snapshots, or point-in-time copies of an ARX volume. This is a table with one line per snapshot. Each line contains the following fields:
Volume, and
Rule all identify the notification rule.
Name is the name of the particular notification snapshot. This is typically the rule name with an integer ID that indicates the order of these snapshots (0 is the newest, 1 is the next-newest, and so on).
Status indicates the result of the coordinated snapshot:
Requested means that someone issued a snapshot create command, or that the rules schedule just invoked a new snapshot.
In Progress indicates that a snapshot is currently underway at the back-end filers.
Created means that all filer snapshots were created successfully.
Created (Sparse) means that one or more filer snapshots failed. This indicates that the notification snapshot is invalid. All filers behind the volume, including the filer used for metadata, must have the manage snapshots setting for notification snapshots to succeed.
Incomplete means that the fencing timeout expired before the snapshot finished on all of its included back-end filers. This implies that snapshot consistency is enabled, causing the volumes VIP(s) to put up a fence against client access until the snapshots finish.
Fence failed also implies that snapshot consistency is enabled, and means that the VIP failed to raise its fence against client access. This indicates an internal-software error; contact F5 Support if you see this.
Policy pause failed indicates another internal-software error, and should not appear during normal operation. As above, contact F5 Support if you see this.
Failed indicates that the snapshot operation failed at one or more back-end filers or servers. Check the snapshot report (available in the detailed output) for more details.
Time Created indicates the time when the final filer finished its snapshot.
Source is Schedule or Manual.
Schedule indicates that the snapshot was invoked by the notification rules schedule (gbl-ns-vol-ntfy), and
Manual means that an administrator manually invoked a snapshot with the snapshot create command.
Snapshot Rule Name are defined by the notification rule command.
Snapshots Enabled is Yes or No, depending on the setting for enable (gbl-ns-vol-ntfy).
Guarantee Consistency is Enabled or Disabled, depending on whether or not the volume uses VIP fencing for its snapshots. The VIP fence, if enabled, blocks all client access to the volume while the filers take their coordinated snapshots. Use the snapshot consistency command to allow or disallow this fence.
Retain Count is the number of snapshots to retain for this rule. If the rule has this many snapshots when it takes a new one, it moves all of the snapshots to the next slot down and then deletes the oldest snapshot. For example, it creates a new rnChgs_0 snapshot, moves the old rnChgs_0 to rnChgs_1, and so on, until it reaches the retain count; then it deletes any remaining snapshots. You can control this with the retain (gbl-ns-vol-ntfy) command.
Schedule is the name of the schedule for the notification rule, if any. Use the schedule (gbl-ns-vol-ntfy) command to assign a schedule to the snapshot rule.
CIFS Directory Name only appears if the volume supports CIFS. This is the pseudo directory that well-informed CIFS clients (administrators) can use to access their snapshots. You can use the snapshot directory cifs-name command to change this name.
NFS Directory Name only appears if the volume supports NFS. This is the pseudo directory that well-informed NFS clients (administrators) can use to access their snapshots. You can use the snapshot directory nfs-name command to change this name.
Directory Display is All Exports (clients see the ~snapshot/.snapshot directory in any front-end share), Volume Root Only (clients only see the directory only in a front-end share of the volumes root directory) or None. You can use the snapshot directory display command to change this.
Hidden File Attribute only appears if the rules volume supports CIFS. This is Set if the special ~snapshot directory has its hidden DOS attribute raised, or Not Set otherwise. Use an optional argument in the snapshot directory display command to control this setting. This option is irrelevant to NFS clients.
Restricted Access Configured also only appears if the volume supports CIFS. This is Yes or No depending on whether or not someone used the snapshot privileged-access command. If this is Yes, a small set of privileged CIFS clients can access the volumes snapshots. These clients are members of a Windows-Management-Authorization (WMA) group with permission to monitor snapshots. These privileged clients are typically administrators. This option has no impact on NFS clients.
VSS Mode only appears if the volume supports CIFS. This field indicates the client-machine versions for which the volume supports the Volume Shadow-copy Service (VSS). VSS is an intuitive interface that Windows clients can use to access their snapshots. This is Windows XP (the volume supports VSS for Windows XP client machines, as well as newer machines), Pre-Windows XP (the volume also supports VSS for Windows-2000 clients), or None. Use the snapshot vss-mode command to change this setting. As above, this option has no impact on NFS clients.
After the notification rule has run at least once, additional tables appear for each of its snapshots. The first table, Snapshot Summary - snapshot-name summarizes the notification snapshot. This table contains the following fields:
Snapshot Name is the name of the notification snapshot.
Time Requested is the last date and time that someone issued an ARX command (such as snapshot create or snapshot verify) for this notification snapshot.
Time Created shows the date and time that the last filer behind the volume completed its snapshot or checkpoint operation. In progress appears if a snapshot is currently underway.
Last Time Verified is the last time someone ran snapshot verify against this notification snapshot.
Guidelines: Snapshot Summary - snapshot-name (Cont.)
Request shows the currently-active request for this ARX snapshot. This is one of the following:
Idle indicates that no command is currently running on this snapshot.
Create means the rule is currently creating a notification snapshot. This indicates either a scheduled snapshot or a snapshot invoked by the snapshot create command.
Manage shows that the rule is incorporating an existing snapshot to an ARX snapshot. This means that someone invoked the snapshot manage command.
Delete indicates that filer snapshots are being removed from behind this rule. This request comes from the snapshot remove command.
Remove indicates that someone invoked no notification rule to delete the current notification rule.
Verify shows that someone invoked snapshot verify to verify the integrity of all filer snapshots behind this notification snapshot.
Cleanout indicates that a notification snapshot failed and the snapshot software is removing filer snapshots that are inconsistent with one another. This should be rare. If you see this, you can use the show cores command to check for core-memory files from the snapshot software. The clean-out operation generates a snapshot report that you can see with the show reports command.
Snapshot State shows the results of the most-recent snapshot operation. This is either Complete or Incomplete. Complete indicates a successful snapshot on all of the volumes shares. An Incomplete state only applies to a snapshot verify operation: this indicates that one of the included shares is now missing its back-end snapshot or checkpoint.
Snapshot Origin is Schedule or Manual. This has the same possible values as the Source field in the summary view:
Schedule indicates that the snapshot was invoked by the notification rules schedule (gbl-ns-vol-ntfy), and
Manual means that an administrator manually invoked a snapshot with the snapshot create command.
Report Name identifies the report for the rules most-recent action. You can use show reports report-name to view this report.
Share Name is the name of the share in the ARX volume, defined by the share command.
Filer is a header for the remaining fields.
Name is the external-filer name, defined with the external-filer command.
NFS Share is the name of the NFS export at the filer.
CIFS Share is the name of the share at the filer.
Volume is the name of the filer volume behind the above filer share.
Volume Snapshot is the name of the filer snapshot.
If any of the volumes shares were administratively excluded from the snapshot, an Excluded Shares section appears to describe them. You can use no manage snapshots to exclude all shares on a filer. A notification rule requires that all storage shares are in every snapshot, so this causes the notification snapshot to fail. These tables contain the same fields that are in the Included Shares tables, except the fields to describe the back-end snapshot.
provA# show notification
provA# show notification namespace provMed volume /mds rule mdChgs
provA# show notification
provA# show notification namespace provMed volume /mds rule mdChgs
API is a generalized category with meta information about the API itself.
Chassis contains the procedure calls for information about the hardware chassis, and possibly its redundant peer.
Export is a group of procedures related to front-end-CIFS shares (see export (gbl-cifs)) and front-end-NFS exports (export (gbl-nfs)) on the ARX.
FileChangeNotification is a set of procedures for finding out about file changes in a managed volume. These procedures access the snapshots produced by a notification rule (see the Guidelines below).
FileServer is a group of procedures related to external-filers behind the ARX.
ManualMigrateRule is a group of procedures for migrating files from one back-end filer to another behind a managed volume.
Namespace is the heading for procedures related to namespaces on the ARX.
Network is a group of procedures related to network configuration and statistics.
Policy is a group of procedures related to policy configuration, including schedules.
Report is the heading for report-access procedures. These allow an API client to access the same reports you can see with show reports.
Schedules is a group of procedures for creating, editing, and viewing ARX schedules.
Share contains procedure calls related to shares on the ARX.
VirtualService is a group of procedures related to global servers, virtual servers, cifs services, and nfs services on the ARX.
Volume contains procedure calls related to volumes on the ARX.
The procedure calls under FileChangeNotifications require some preparation. For each managed volume where you want to track file changes, create a notification rule. This rule creates snapshots of the volumes metadata and all of its shares. The API monitors the volume over time, and it probes these snapshots as needed to fulfill its procedure calls.
To activate the ARX API, use the management access command followed by the permit command. This opens a port where a SOAP client can send queries to this volume. The HTTP-API port is 83, and the HTTPS-API port is 843.
http://arx-management-ip:83/arx-api/
where arx-management-ip is either the out-of-band management-IP address (interface mgmt) or an in-band (VLAN) management-ip address (interface vlan). The permit command determines which of these address types are available for access. Use show interface mgmt and/or show interface vlan to find the IP addresses for each interface.
https://arx-management-ip:843/arx-api/
where arx-management-ip is a valid management IP, as described above.
You can use this command, show statistics api, to find usage statistics for the API.
provA# show statistics api
provA# show statistics api
Table of Contents   |   << Previous Chapter   |   Next Chapter >>

Was this resource helpful in solving your issue?




NOTE: Please do not provide personal information.



Incorrect answer. Please try again: Please enter the words to the right: Please enter the numbers you hear:

Additional Comments (optional)