Archive Commands
Table 4-1 provides a summary of the archive commands. Each command is described in detail in the section that is listed.
Start Archive
http://host/command.bwt?command=start&type=archive&name=archiveName
&source=proxyName&duration=seconds&framerate=rateNum&loop=loopVal
&desc=description&repos=location&daystolive=liveNum&killproxy=killVal
&force=forceVal
Purpose
Starts an archive process on a media server that records data from a source proxy.
Required Fields
host |
IP address or hostname (hostname.domain) where VSMS is running. By default, VSMS runs on port 80 (HTTP), however, you can use an alternate port, such as port 8080. For example, to specify port 8080, use host:8080. |
command=start |
Start command. The start keyword associates the command with a start action, in this case a start proxy action. The start keyword is a reserved value. |
type=archive |
Archive type. The archive keyword specifies the archive command type. The archive keyword is a reserved value. |
name=archiveName |
Archive name where archiveName specifies the name of the archive instance. The valid value for the archiveName value is an alphanumeric string containing 1 to 256 of the following characters: •Digits (0 to 9) •Upper case letters (A to Z) •Lower case letters (a to z) •Underscore (_) •Hyphen (-) The reserved archiveName value is -1. Note Each archive must have a unique name on a given VSMS host. |
source=proxyName |
The name of the source proxy being archived on the VSMS host. The valid value for proxyName is an alphanumeric string containing 1 to 256 of the following characters: •Digits (0 to 9) •Upper case letters (A to Z) •Lower case letters (a to z) •Underscore (_) •Hyphen (-) The reserved proxyName value is -1. |
Optional Fields
duration=seconds |
The total archive time where seconds specifies the total recording time (in seconds) for the archive. Valid seconds values are integers. The default value is 3600. Note For loop archives, the minimum supported duration is 3600 seconds. |
desc=description |
Archive description where description specifies a brief description of the archive. The valid value for the description value is an alphanumeric string containing 1 to 256 of the following characters: •Digits (0 to 9) •Upper case letters (A to Z) •Lower case letters (a to z) •Underscore (_) •Hyphen (-) •Space character The reserved description value is -1. Note If you do not specify a description, the source proxy name is used as the description. |
framerate=rateNum |
Frame rate where rateNum specifies the maximum number of frames per second requested from the source proxy. Valid values for the rateNum value are 0.001 to 30. Note The archive frame rate cannot be higher than the source proxy frame rate. |
loop=loopVal |
Specifies whether to record a loop or a regular archive. The loopVal value is one of the following boolean values: •0—Regular archive. The archive stops when it reaches the end of its duration. •1—Loop archive. The archive continuously records, overwriting the beginning of the archive when it reaches the end of its duration. The default value is 0. |
repos=location |
DO NOT USE. This parameter is ignored. |
daystolive=liveNum |
Days to live where liveNum specifies the number of days (starting from the day the archive stops) that the archive is stored before being removed from the system. Valid liveNum values are integers. The default value is 0, which permanently stores the archive in the repository. |
killproxy=killVal |
Specifies whether to pause the archive. The killVal value is one of the following boolean values: •0—Immediately pauses the archive. •1—Pauses the archive after the archiver process completes. The default value is 0. |
force=forceVal |
Specifies whether to ignore the storage space check and start the archive. The forceVal value is one of the following boolean values: •0—The system checks whether there is enough space to store the archive. If there is insufficient storage space, the archiver process does not start. •1—Ignores the storage space check and starts the archive. If there is insufficient storage space for the archive, VSM grooms the oldest data to make room for the new archive. The default value is 0. |
Return Values
A standard HTTP/1.x header followed by:
Return Code: <[archive name] or -1 output>
[archive name] Successful completion of the URL command
-1 Error in execution of the URL command
Examples
Starting a Non-Loop Archive
The following example starts an archive named officeCam that stops recording after 60 minutes:
http://vsms.cisco.com/command.bwt?command=start&type=archive&name=officeCamFor60Min
&source=officeCam&duration=3600&force=1
Starting a 24-Hour Loop Archive
The following example starts an archive named officeCam that records in a continuous 24 hour loop:
http://vsms.cisco.com/command.bwt?command=start&type=archive
&name=officeCamFor24Hr&source=officeCam&duration=86400&loop=1
Starting a 2-Hour Archive
The following example starts a 2-hour archive that pauses when complete:
http://vsms.cisco.com/command.bwt?command=start&type=archive
&name=audio_arch&source=audiocast&duration=7200&killproxy=1
Update Archive
Updates an existing archive with different parameter values.
The following APIs are available for updating existing archives:
•Update JPEG Archive Frame Rate
•Update Archive Expiration Time
Update JPEG Archive Frame Rate
http://host/command.bwt?command=update&type=archive&name=archiveName
&framerate=rateNum
Purpose
Updates the frame rate of a JPEG archive.
Required Fields
host |
IP address or hostname (hostname.domain) where VSMS is running. By default, VSMS runs on port 80 (HTTP), however, you can use an alternate port, such as port 8080. For example, to specify port 8080, use host:8080. |
command=update |
Update command. The update keyword associates the command with an update action (an update archive action in this case). The update keyword is a reserved value. |
type=archive |
Archive type. The archive keyword specifies the archive command type. The archive keyword is a reserved value. |
name=archiveName |
Archive name where archiveName specifies the name of the archive instance. The valid value for the archiveName value is an alphanumeric string containing 1 to 256 of the following characters: •Digits (0 to 9) •Upper case letters (A to Z) •Lower case letters (a to z) •Underscore (_) •Hyphen (-) The reserved archiveName value is -1. Note Each archive must have a unique name on a given VSMS host. |
framerate=rateNum |
Frame rate where rateNum specifies the maximum number of JPEG frames per second requested from the source proxy. Valid values for the rateNum value are 0.001 to 30. Note The archive frame rate cannot be higher than the source proxy frame rate. |
Return Values
A standard HTTP/1.x header followed by:
Return Code: <[archive name] or -1 or output>
[archive name] Successful completion of the URL command
-1 Error in execution of the URL command
Examples
The following example updates the frame rate of a JPEG archive named Archive30 to a value of 15:
http://vsms.cisco.com/command.bwt?command=update& type=archive&name=Archive30
&framerate=15
Update Archive Expiration Time
Caution
Use this API with caution.
http://host/command.bwt?command=update&type=archive&name=archiveName
&daystolive=liveNum
Purpose
Updates an existing archive with the number of days (starting from the day the archive stops) that the archive is stored before being removed from the system.
Required Fields
host |
IP address or hostname (hostname.domain) where VSMS is running. By default, VSMS runs on port 80 (HTTP), however, you can use an alternate port, such as port 8080. For example, to specify port 8080, use host:8080. |
command=update |
Update command. The update keyword associates the command with an update action (an update archive action in this case). The update keyword is a reserved value. |
type=archive |
Archive type. The archive keyword specifies the archive command type. The archive keyword is a reserved value. |
name=archiveName |
Archive name where archiveName specifies the name of the archive instance. The valid value for the archiveName value is an alphanumeric string containing 1 to 256 of the following characters: •Digits (0 to 9) •Upper case letters (A to Z) •Lower case letters (a to z) •Underscore (_) •Hyphen (-) The reserved archiveName value is -1. Note Each archive must have a unique name on a given VSMS host. |
daystolive=liveNum |
Days to live where liveNum specifies the number of days (starting from the day the archive stops) that the archive is stored before being removed from the system. Valid liveNum values are integers. The default value is 0, which permanently stores the archive in the repository. |
Return Values
A standard HTTP/1.x header followed by:
Return Code: <[archive name] or -1 or output>
[archive name] Successful completion of the URL command
-1 Error in execution of the URL command
Examples
The following example updates the archive named Archive30 to expire after 10 days:
http://vsms.cisco.com/command.bwt?command=update&type=archive&name=Archive30
&daystolive=10
Rename Archive
http://host/rename_archive.bwt?command=rename&oldname=archiveName
&newname=archiveName
Purpose
Renames an archive that is not currently running.
Required Fields
host |
IP address or hostname (hostname.domain) where VSMS is running. By default, VSMS runs on port 80 (HTTP), however, you can use an alternate port, such as port 8080. For example, to specify port 8080, use host:8080. |
command=rename |
Rename command. The rename keyword associates the command with a rename action, in this case a rename archive action. The rename keyword is a reserved value. |
oldname=archiveName |
Old archive name where archiveName specifies the name of the archive instance. The valid value for the archiveName value is an alphanumeric string containing 1 to 256 of the following characters: •Digits (0 to 9) •Upper case letters (A to Z) •Lower case letters (a to z) •Underscore (_) •Hyphen (-) The reserved archiveName value is -1. Note Each archive must have a unique name on a given VSMS host. |
newname=archiveName |
New archive name where archiveName specifies the name of the archive instance. The valid value for the archiveName value is an alphanumeric string containing 1 to 256 of the following characters: •Digits (0 to 9) •Upper case letters (A to Z) •Lower case letters (a to z) •Underscore (_) •Hyphen (-) The reserved archiveName value is -1. Note Each archive must have a unique name on a given VSMS host. |
Return Values
A standard HTTP/1.x header followed by:
Return Code: <1 OK or -1 or output>
1 OK Successful completion of the URL command
-1 Error in execution of the URL command
Examples
The following command renames an archive from ABC to BCD.
http://vsms.cisco.com/command.bwt?command=rename&oldname=ABC&newname=BCD
Stop Archive
http://host/command.bwt?command=stop&type=archive&name=archiveName
Purpose
Stops a running archive.
Required Fields
host |
IP address or hostname (hostname.domain) where VSMS is running. By default, VSMS runs on port 80 (HTTP), however, you can use an alternate port, such as port 8080. For example, to specify port 8080, use host:8080. |
command=stop |
Stop command. The stop keyword associates the command with a stop action. The stop keyword is a reserved value. |
type=archive |
Archive type. The archive keyword specifies the archive command type. The archive keyword is a reserved value. |
name=archiveName |
Archive name where archiveName specifies the name of the archive instance. The valid value for the archiveName value is an alphanumeric string containing 1 to 256 of the following characters: •Digits (0 to 9) •Upper case letters (A to Z) •Lower case letters (a to z) •Underscore (_) •Hyphen (-) The reserved archiveName value is -1. Note Each archive must have a unique name on a given VSMS host. |
Return Values
A standard HTTP/1.x header followed by:
Return Code: <[archive name] or -1 or output>
[archive name] Successful completion of the URL command
-1 Error in execution of the URL command
Examples
The following command stops an archive with server name ABC.
http://vsms.cisco.com/command.bwt?command=stop&type=archive&name=ABC
Remove Archive
http://host/cgi-bin/smanager.bwt?command=remove&name=archiveName
Purpose
Removes a stopped archive from the repository.
Required Fields
host |
IP address or hostname (hostname.domain) where VSMS is running. By default, VSMS runs on port 80 (HTTP), however, you can use an alternate port, such as port 8080. For example, to specify port 8080, use host:8080. |
command=remove |
Remove command. The remove keyword associates the command with a remove action. The remove keyword is a reserved value. |
type=archive |
Archive type. The archive keyword specifies the archive command type. The archive keyword is a reserved value. |
name=archiveName |
Archive name where archiveName specifies the name of the archive instance. The valid value for the archiveName value is an alphanumeric string containing 1 to 256 of the following characters: •Digits (0 to 9) •Upper case letters (A to Z) •Lower case letters (a to z) •Underscore (_) •Hyphen (-) The reserved archiveName value is -1. Note Each archive must have a unique name on a given VSMS host. |
Return Values
A standard HTTP/1.x header followed by:
Return Code: <0 [archive name] or -1>
0 [archive name] Successful completion of the URL command
-1 Error in execution of the URL command
Examples
The following command removes archive ABC.
http://vsms.cisco.com/cgi-bin/smanager.bwt?command=remove&name=ABC
List All Archives
http://host/info.bwt?type=archive&display=dispFormat
Purpose
Displays information about all archives on a VSMS host.
Required Fields
host |
IP address or hostname (hostname.domain) where VSMS is running. By default, VSMS runs on port 80 (HTTP), however, you can use an alternate port, such as port 8080. For example, to specify port 8080, use host:8080. |
type=archive |
Archive type. The archive keyword specifies the archive command type. The archive keyword is a reserved value. |
Optional Fields
display=dispFormat |
Type of display output where dispFormat specifies the format to use when displaying the list of running proxies. Valid dispFormat values include the following reserved keywords: •html—Hypertext markup language format •text—Plain text format •ssv—Space-separated value format The default dispFormat value is html. |
Return Values
A standard HTTP/1.x header followed by:
Return Code: <[archive list] or -1>
[archive list] Successful completion of the URL command
-1 Error in execution of the URL command
Examples
The following command lists all the archives in SSV format.
http://vsms.cisco.com/info.bwt?type=archive&display=ssv
List All Running Archives
http://host/info.bwt?type=archiver&display=dispFormat
Purpose
Displays information for all running archives.
Required Fields
host |
IP address or hostname (hostname.domain) where VSMS is running. By default, VSMS runs on port 80 (HTTP), however, you can use an alternate port, such as port 8080. For example, to specify port 8080, use host:8080. |
type=archiver |
Archive type. The archiver keyword specifies the archive command type. The archiver keyword is a reserved value. |
Optional Fields
display=dispFormat |
Type of display output where dispFormat specifies the format to use when displaying the list of running proxies. Valid dispFormat values include the following reserved keywords: •html—Hypertext markup language format •text—Plain text format •ssv—Space-separated value format The default dispFormat value is html. |
Return Values
A standard HTTP/1.x header followed by:
Return Code: <[running archive list] or -1>
[running archive list] Successful completion of the URL command
-1 Error in execution of the URL command
Examples
The following command lists all the running archives in SSV format.
http://vsms.cisco.com/info.bwt?type=archiver&display=ssv
Get Archive MediaType
http://host/info.bwt?type=archive&name=archiveName&property=mediatype
Purpose
Retrieves the media type value for an archive.
Required Fields
host |
IP address or hostname (hostname.domain) where VSMS is running. By default, VSMS runs on port 80 (HTTP), however, you can use an alternate port, such as port 8080. For example, to specify port 8080, use host:8080. |
type=archive |
Archive type. The archive keyword specifies the archive command type. The archive keyword is a reserved value. |
name=archiveName |
Archive name where archiveName specifies the name of the archive instance. The valid value for the archiveName value is an alphanumeric string containing 1 to 256 of the following characters: •Digits (0 to 9) •Upper case letters (A to Z) •Lower case letters (a to z) •Underscore (_) •Hyphen (-) The reserved archiveName value is -1. Note Each archive must have a unique name on a given VSMS host. |
property=mediatype |
Media type. The mediatype keyword requests the media type value for the specified archive, which is a JPEG, MPEG, or audio value. The mediatype keyword is a reserved value. |
Return Values
A standard HTTP/1.x header followed by:
Return Code: <[jpeg | mpeg2-v | mpeg4-v | h264-v | audio] or -1 or output>
[jpeg | mpeg2-v | mpeg4-v | h264-v | audio] Successful completion of the URL command
-1 Error in execution of the URL command
Examples
The following example retrieves the media type value for the archive named fooArchive:
http://vsms.cisco.com/info.bwt?type=archive&name=fooArchive&property=mediatype
Get Archive Details
Gets archive details.
The following APIs are available for retrieving detailed archive recording information:
•Get Archive Recording Details
•Archive Details
Get Archive Recording Details
http://host/info.bwt?type=archive&property=mmconf_properties&display=dispFormat &name=archiveName
Purpose
Displays recording details for an archive.
Caution
This command is CPU intensive and should not be run frequently.
Required Fields
host |
IP address or hostname (hostname.domain) where VSMS is running. By default, VSMS runs on port 80 (HTTP), however, you can use an alternate port, such as port 8080. For example, to specify port 8080, use host:8080. |
type=archive |
Archive type. The archive keyword specifies the archive command type. The archive keyword is a reserved value. |
name=archiveName |
Archive name where archiveName specifies the name of the archive instance. The valid value for the archiveName value is an alphanumeric string containing 1 to 256 of the following characters: •Digits (0 to 9) •Upper case letters (A to Z) •Lower case letters (a to z) •Underscore (_) •Hyphen (-) The reserved archiveName value is -1. Note Each archive must have a unique name on a given VSMS host. |
property=mmconf_properties |
Recording information. The mmconf_properties keyword requests the XML-formatted recording details for the specified archive. The mmconf_properties keyword is a reserved value. |
Optional Fields
display=dispFormat |
Type of display output where dispFormat specifies the format to use when displaying the list of running proxies. Valid dispFormat values include the following reserved keywords: •html—Hypertext markup language format •text—Plain text format •ssv—Space-separated value format The default dispFormat value is html. |
Return Values
Detailed recording information about the archive.
Examples
The following command displays the detailed recording information for the archive named ABC.
http://vsms.cisco.com/info.bwt?type=archive&name=ABC&property=mmconf_properties
Archive Details
http://host/info.bwt?type=archive&property=archive_details&display=dispFormat &name=archiveName
Purpose
Displays details for an archive, excluding information about the first and last frame time.
Required Fields
host |
IP address or hostname (hostname.domain) where VSMS is running. By default, VSMS runs on port 80 (HTTP), however, you can use an alternate port, such as port 8080. For example, to specify port 8080, use host:8080. |
type=archive |
Archive type. The archive keyword specifies the archive command type. The archive keyword is a reserved value. |
name=archiveName |
Archive name where archiveName specifies the name of the archive instance. The valid value for the archiveName value is an alphanumeric string containing 1 to 256 of the following characters: •Digits (0 to 9) •Upper case letters (A to Z) •Lower case letters (a to z) •Underscore (_) •Hyphen (-) The reserved archiveName value is -1. Note Each archive must have a unique name on a given VSMS host. |
property=archive_details |
Recording information. The archive_details keyword requests the XML-formatted recording details for the specified archive, excluding information about the first and last frame time. The archive_details keyword is a reserved value. |
Optional Fields
display=dispFormat |
Type of display output where dispFormat specifies the format to use when displaying the list of running proxies. Valid dispFormat values include the following reserved keywords: •html—Hypertext markup language format •text—Plain text format •ssv—Space-separated value format The default dispFormat value is html. |
Return Values
Detailed recording information about the archive, excluding information about the first and last frame time.
Examples
The following command displays the detailed recording information for the archive named ABC.
http://vsms.cisco.com/info.bwt?type=archive&name=ABC&property=archive_details
Get Archive Monitoring Detail
http://host/info.bwt?type=archive&name=archiveName&property=armon_detail
Purpose
Retrieves detailed archive performance information.
Caution
This command is CPU intensive and should not be run frequently.
Required Fields
host |
IP address or hostname (hostname.domain) where VSMS is running. By default, VSMS runs on port 80 (HTTP), however, you can use an alternate port, such as port 8080. For example, to specify port 8080, use host:8080. |
type=archive |
Archive type. The archive keyword specifies the archive command type. The archive keyword is a reserved value. |
name=archiveName |
Archive name where archiveName specifies the name of the archive instance. The valid value for the archiveName value is an alphanumeric string containing 1 to 256 of the following characters: •Digits (0 to 9) •Upper case letters (A to Z) •Lower case letters (a to z) •Underscore (_) •Hyphen (-) The reserved archiveName value is -1. Note Each archive must have a unique name on a given VSMS host. |
property=armon_detail |
Archive monitoring summary property. The armon_detail keyword requests XML information that shows detailed performance information for an archive. The armon_detail keyword is a reserved value. |
Return Values
XML information that shows detailed performance information about the archive.
Examples
The following example retrieves the XML information that shows detailed recording information for the archive ABC.
http://vsms.cisco.com/info.bwt?type=archive&name=ABC&property=armon_detail
Get Archive Monitoring Summary
http://host/info.bwt?type=archive&name=archiveName&property=armon_summary
Purpose
Retrieves summary archive performance information.
Caution
This command is CPU intensive and should not be run frequently.
Required Fields
host |
IP address or hostname (hostname.domain) where VSMS is running. By default, VSMS runs on port 80 (HTTP), however, you can use an alternate port, such as port 8080. For example, to specify port 8080, use host:8080. |
type=archive |
Archive type. The archive keyword specifies the archive command type. The archive keyword is a reserved value. |
name=archiveName |
Archive name where archiveName specifies the name of the archive instance. The valid value for the archiveName value is an alphanumeric string containing 1 to 256 of the following characters: •Digits (0 to 9) •Upper case letters (A to Z) •Lower case letters (a to z) •Underscore (_) •Hyphen (-) The reserved archiveName value is -1. Note Each archive must have a unique name on a given VSMS host. |
property=armon_summary |
Archive monitoring summary property. The armon_summary keyword requests XML information that shows the recording rate of the archive in MB per second. The armon_summary keyword is a reserved value. |
Return Values
XML information that shows recording rate of the archive in MB per second
Examples
The following example retrieves the XML information that shows detailed recording information for the archive ABC.
http://vsms.cisco.com/info.bwt?type=archive&name=ABC&property=armon_summary
Create Archive Clip
http://host/cgi-bin/smanager.bwt?command=save&source=archiveName&startutc=utcDate
&stoputc=utcDate&name=target_id&savemode=local&desc=description
&saveformat=clipType&daystolive=liveNum¬ifyurl=notifyUrl
Purpose
Creates a clip from an archive.
Required Fields
host |
IP address or hostname (hostname.domain) where VSMS is running. By default, VSMS runs on port 80 (HTTP), however, you can use an alternate port, such as port 8080. For example, to specify port 8080, use host:8080. |
command=save |
Save command. The save keyword associates the command with a save action, in this case saving a clip from an archive. The save keyword is a reserved value. |
source=archiveName |
Source archive where archiveName specifies the name of the archive instance. This is the parent archive from which to create the clip. The valid value for the archiveName value is an alphanumeric string containing 1 to 256 of the following characters: •Digits (0 to 9) •Upper case letters (A to Z) •Lower case letters (a to z) •Underscore (_) •Hyphen (-) The reserved archiveName value is -1. Note Each archive must have a unique name on a given VSMS host. |
savemode=local |
Save location for the archive clip. The local keyword specifies that only local clips are supported. The local keyword is a reserved value. |
startutc=utcDate |
Start date of the child clip, specified in UTC milliseconds. Verify the parent archive contains data for this date. |
stoputc=utcDate |
Stop date of the child clip, specified in UTC milliseconds. Make sure the parent archive contains data for this date. |
Optional Fields
name=target_id |
Target archive name where target_id specifies the name of the archive instance. The valid value for the target_id value is an alphanumeric string containing 1 to 256 of the following characters: •Digits (0 to 9) •Upper case letters (A to Z) •Lower case letters (a to z) •Underscore (_) •Hyphen (-) The reserved archiveName value is -1. Note Each archive must have a unique name on a given VSMS host. |
desc=description |
Archive description where description specifies a brief description of the archive. The valid value for the description value is an alphanumeric string containing 1 to 20 of the following characters: •Digits (0 to 9) •Upper case letters (A to Z) •Lower case letters (a to z) •Underscore (_) •Hyphen (-) •Space character The reserved description value is -1. If this parameter is not specified, VSMS will store the name of the proxy source in the description field. |
repos=location |
DO NOT USE. This parameter is ignored. |
saveformat=clipType |
Save format where clipType specifies the type of archive clip to generate. Valid clipType values include the following keywords: •regular—Regular streamable archive clip •bwm—BWM archive clip •bwx— BWX secure video clip The default clipType value is regular. |
daystolive=liveNum |
Days to live where liveNum value specifies the number of days (starting from the day the clip is created) that the clip is stored before being removed from the repository. Valid liveNum values are integers. The default value is 0, which permanently stores the clip in the repository. |
notifyurl=notifyUrl |
Format: [http://host/handler_path] URL to send upon the successful completion or failure of a clip. This is used to report status to the application after the clipping process finishes execution. |
Return Values
A standard HTTP/1.x header followed by:
Return Code: <0 or -1 output>
0 Successful completion of the URL command
-1 Error in execution of the URL command
VSMS will return a status code after the parameters have been validated. The save clip operation will run in the background. VSMS will not send a second return code when the clip is completed, but a handler can be configured at the save clip's notification URL to receive notification if a clip has succeeded or failed.
Examples
The following command saves a clip from archive ABC, to localhost on port 80, beginning at 1020530754089 (UTC milliseconds) and ending at 1020530786232 (UTC milliseconds). VSMS will create the name for this archive clip and create a virtual clip on the local host.
http://vsms.cisco.com/cgi-bin/smanager.bwt?command=save&startutc=1020530754089&stoputc=102
0530786232&source=ABC&savemode=local&saveformat=regular