A.0 XML Elements and Attributes for ArkConfig

This section defines the XML elements and attributes that you use to configure versioning jobs for your Novell Archive and Version Services for OES 11 SP3 server. The XML elements have a particular hierarchy that you must keep in mind as you define the Basic element, Defaults element, and multiple Job elements. See Figure A-1 to understand the parent-child relationships between XML elements defined for the etc/opt/novell/arkManager/conf/arkConfig.xml file.

The following table defines the XML elements and attributes that you use in the /var/opt/novell/arkmanager/arkConfig.xml file. Some elements appear first as children of elements in the next-higher level of the hierarchy and as parents to their own set of child elements in the next-lower level of the hierarchy.

The examples provided for the elements are sample code to illustrate how the configured properties appear in the XML file. You must modify the properties to meet your specific needs as you create your etc/opt/novell/arkManager/conf/arkConfig.xml file.

For a sample of the basic configuration, see Sample Configuration for arkConfig.xml.

NOTE:The user credentials for eDirectory and PostgreSQL database are not authenticated using arkConfig.xml. For security reasons, the credentials are passed using YaST and stored in CASA store.

Figure A-1 Hierarchical Parent-Child Relationships between XML Elements Used in the arkConfig.xml File

Table A-1 Elements of the arkConfig.xml File

Parent Element

Child Elements and Attributes

Description

 
<arkConfig>

(Root element)

<basic>

A single Basic tag set surrounds the management information that applies to all jobs. Its child elements specify where to display the log, the authentication information, and the storage location where the archive data (versions) reside.

At a minimum, configure the <authentication> information for ArkManager 2.0 to run.

For information about its child elements, see <basic> in the Parent Element column of this table. 

<defaults>

A single Defaults tag set surrounds the child elements that define the default settings to use if the elements are not set in individual jobs.

Each job uses the values configured in the Defaults element only for those values that are not otherwise set for that job.

For information about its child elements, see <defaults> in the Parent Element column of this table. 

<job>

A Job tag set surrounds the child elements that define the settings for a given job. Create one job for each unique information set that you want to version. An archive server can version a given source volume with only one job.

The values configured in a given job override the default settings only for that job. If a value is not set in the Job element, the default settings apply for only that element.

For information about its child elements, see <job> in the Parent Element column of this table. 

<basic>

(Child to <arkConfig>)

 
<displayLog/>

(Optional) If this tag is included in the arkConfig.xml file, it prints log entries for all jobs to the server’s console screen in addition to their normal display in the Archive / Version Log.

This is an empty element. It has no child elements and defines no data values. Either the shortened version or the long version of this element is valid. For example, either of the following formats work:

<displayLog/>

<displayLog></displayLog>

<authentication>

Contains child elements that provide information about the administrator user. This user must have rights to all servers being accessed by this archive server. Child elements also define the ArkSQL database user, password, and port number. The ArkSQL user needs server-specific ArkSQL rights.

The <authentication> information must be set before ArkManager can run.

For information about its child elements, see <authentication> in the Parent Element column of this table.

NOTE:The user credentials for eDirectory and PostgreSQL database are not authenticated using arkConfig.xml. For security reasons, the credentials are passed using YaST and stored into CASA store.

 
<archivePath>

Specifies the local path to the NSS volume in the archive server where the archived versions of files are stored. 

<archivePath>
volume_name:\directory\
</archivePath>

Placing a backslash between the colon and the directory name, as shown in this example, is optional.

NOTE:In OES2 or later the <archivePath> is case sensitive.

If you are setting up an active-passive clustered solution for the archive server using Novell Cluster Services, make sure to specify the path to the virtual storage location.

 
<defaults>

(Child to <arkConfig>)

 
<fullCopy/>

For information about these child elements, see the Job element (<job>) in this table.

The Defaults element can contain any tags that you use in a Job element, except for <name>, <volume>, and <stopped/>.

Although you can have multiple Job elements, only a single Defaults element appears in the arkConfig.xml file.

 
<noFullCopy/>

<source>

<frequency>

<deletePolicy>

<job>

(Child to <arkConfig>)

 
<name>

Specifies the unique name of this versioning job. This name can contain spaces.

You might want the job name to reflect information about the data that is being versioned. For example, if you have a job that versions data for a user1 volume on the svr1 server, you might name the job:

<name>user1[svr1]</name>

Use the <name> tag as a child only of the Job element; it is invalid in the Defaults element. 

<fullCopy/>

(Optional) If used, sets a flag so that the job copies all files that pass the filter from the source volume to the archive database the first time the job runs or if a full copy runs but did not finish previously.

In any given Job element or Defaults element, use <fullCopy/> or use <noFullCopy/>, not both. If neither one is specified, <fullCopy/> is the default software setting.

This is an empty element; it has no child elements and no data values. 

<noFullCopy/>

(Optional) If used, sets a flag so that the job does not copy all files that pass the filter from the source volume to the archive database the first time the job runs.

This is an empty element; it has no child elements and no data values. 

<source>

Contains child elements that define the specific server context, server, paths, directories, or file types to be archived for this job.

For information about its child elements, see <source> in the Parent Element column of this table.

NOTE:If a job is configured using IP address or hostname in the <source> element, ensure that the IP address or hostname is same as the IP address or hostname of the server where the data to be versioned is located.

 
<frequency>

Contains child elements that define the start time and intervals for versioning in this job.

For information about its child elements, see <frequency> in the Parent Element column of this table. 

<job>

(cont’d)

 
<deletePolicy>

Contains child elements that specify when to delete a version, such as by age of the version (elapsed time of creation), by the number of versions that exist (oldest deleted first), or by the interval of time before the next versioning process.

For information about its child elements, see <deletePolicy> in the Parent Element column of this table. 

<stopped/>

Specify this property to define the job but leave it in a Stopped state until you manually activate the job. If the Stopped parameter is not used, the job starts, according to the Run Schedule settings, the next time ArkManager runs.

Use the <stopped/> tag as a child only of the Job element; it is invalid in the Defaults element. 

<authentication>

(Child to <basic>)

 
<eDirectory>

Contains child elements that specify the eDirectory authentication information, including the administrator user, the password, and the eDirectory tree where the administrator user, archive server, and source servers reside.

For information about its child elements, see <eDirectory> in the Parent Element column of this table.

 
<database>

Contains child elements that contain information about the archive server’s ArkSQL database. This user must have server-specific rights to the ArkSQL server.

For information about its child elements, see <database> in the Parent Element column of this table. 

<eDirectory>

(Child to <authentication>)

 
<user>

This attribute is not used for user authentication.

 
<password>

This attribute is not used for user authentication.

 
<tree>

This attribute is not used for user authentication.

NOTE:The eDirectory credentials are passed using YaST and are stored in the CASA store.

 
<database>

(Child of <authentication>)

 
<user>

This attribute is not used for user authentication.

 
<password>

This attribute is not used for user authentication.

 
<portNumber>

This attribute is not used for user authentication.

NOTE:The PostgreSQL credentials are passed using YaST and are stored in the CASA store.

 
<source>

(Child to <defaults> and to <job>)

 
<snapshotPool>

Specifies the name of the destination pool where a snapshot of the source volume is created temporarily at the beginning of each versioning. For example:

<snapshotPool>pool_name
</snapshotPool>

Snapshots make it possible to save point-in-time versions of all eligible source files, even if a file is open at the time. Eligible files are those files that exist at the end of the epoch, changed during the epoch, and met the filter requirements.

By default, if no snapshot pool is specified, ArkManager copies the eligible source files directly from the source volume. Exclusively open files cannot be versioned and data might be inconsistent.

If the specified snapshot pool is inactive or otherwise not available when a versioning job begins, the job copies the files directly from the source volume.

 

<freeSpaceID>

ID of the free space object to be used for storing snapshot data. For example, hda_freespace1 or hda.

 

<numSectors>

Specifies the number of sectors on free space to be used for storing snapshot data. The value needs to be an integer, for example, 419430400.

 

 
<serverContext>

Specifies the unique name of the context of the server that hosts the source volume, which contains the data that the job versions and saves to the archive database.

Type the server context in the Novell common dot format, from lowest to highest level. It does not include the tree. For example: 

<serverContext>
grp1.dept1.site1.examplecompany
</serverContext>

<serverContext>
sales.mktg.eur.acme
</serverContext>

 

 
<server>

Specifies the unique name of the server in the specified context where the original data is stored. For example, to specify a server named srv1:

<server>srv1</server>

Use the <server> tag as a child only of the Job element; it is invalid in the Defaults element.

 
<source>

(cont’d)

 
<volume>

Specifies the unique name of the OES 11 SP3 NSS volume in the specified source server where the original data is stored.

For example, to specify user1 as the source volume:

<volume>user1</volume>

Do not place a colon after the name of the source volume.

Use the <volume> tag as a child only of the Job element; it is invalid in the Defaults element.

 
<filter>

<filter overrideDefaults="false">

<filter overrideDefaults="true">

(Optional) Contains child elements and attributes that specify the criteria for filtering data so that only selected data is versioned.

Use the attributes optionally to indicate whether the filter is to be used in combination with filters set in the Defaults element (false) or if the filter is to be used in place of the filters set in the Defaults element (true).

For information about its child elements, see <filter> in the Parent Element column of this table. 

<filter>

(Child to <source>)

 
<include>

(Optional) Contains child elements that specify traits of data you want to include in the job.

For information about its child elements, see <include> in the Parent Element column of this table. 

<exclude>

(Optional) Contains child elements that specify traits of data you want to exclude in the job.

For information about its child elements, see <exclude> in the Parent Element column of this table. 

<include>

(Child to <filter>)

 
<path>

(Optional) Specifies the relative path of directories in the specified volume that you want to include in the versioning process. If you want to include eligible files only in the specified paths, make sure to exclude the root path in an exclude path statement.

For example, to specify a relative path of the volume_name:\dept1\data directory that contains data you want to include:

<include>
  <path>\dept1\data\</path>
</include>

Repeat this element for each directory path in the specified volume that contains data that you want to version.

 
<extension>

(Optional) Specifies the extension of files in the specified volume that you want to include in the versioning process. Use the preceding dot followed by the characters of the file extension.

Repeat this element for each file extension type that you want to version.

For example, to specify that you want to version only files with no extension (.) and files with .xxx and .yyy extensions:

<include>
  <extension>.</extension> 
     <!-- No extension -->
  <extension>.xxx</extension>
  <extension>.yyy</extension>
</include>

<pattern>

(Optional) Specifies the regular expression pattern to match for files that you want to include in the versioning process.

For example, to set criteria to include only files with names that start with the letter “a”.

<include>
  <pattern>.*\\a.*</pattern>
</include>

Repeat this element for each pattern that you want to match to identify files for versioning.

This element does not support the full set of PERL regular expressions. For more information, see Pattern Elements.

 
<include>

(cont’d)

 
<wildcard>

(Optional) Functions like a wildcard in directory searches. Replace characters with an asterisk (*) to search for files that match. For example, to include files that start with d of type .sxi:

<include>
  <wildcard>d*sxi</wildcard>
</include>

<exclude>

(Child to <filter>)

 
<path>

(Optional) Specifies the relative path of directories in the specified volume that you want to exclude from the versioning process.

For example, to specify a relative path of the volume_name:\dept1\apps directory that contains application data you want to exclude from versioning:

<exclude>
  <path>\dept1\apps\</path>
</exclude>

Repeat this element for each directory path in the specified volume that contains data that you do not want to version.

 
<extension>

(Optional) Specifies the extension of files in the specified volume that you want to exclude from the versioning process. Use the preceding dot followed by the characters of the file extension.

Repeat this element for each file extension type that you do not want to version.

For example, to specify that you want to exclude .zzz files from versioning:

<exclude>
  <extension>.zzz</extension>
</exclude>

<exclude>

(cont’d)

 
<pattern>

(Optional) Specifies the regular expression pattern to match for files that you want to exclude from the versioning process.

For example, to set criteria to exclude files with names that start with the letter “a”:

<exclude>
  <pattern>.*\\a.*</pattern>
</exclude>

Repeat this element for each pattern that you want to match to identify files to be excluded from versioning.

This element does not support the full set of PERL regular expressions. For more information, see Pattern Elements.

 
<wildcard>

(Optional) Functions like a wildcard in directory searches. Replace characters with an asterisk (*) to search for files that match. For example, to exclude files that start with d of type .tmp:

<exclude>
  <wildcard>d*tmp</wildcard>
</exclude>

<frequency>

(Child to <defaults> and to <job>)

 
<time>

(Conditional) Contains child elements that specify the start time, based on a 24-hour local time scale, of jobs that are scheduled to occur on specified days of the week. A valid hour entry is an integer value ranging from 0 to 23.

Use either the Time element or Interval element, but not both in the same Job element.

For example, to start the versioning at 11:15 p.m. (23:45) every day of the week:

<frequency>

  <time>

    <start>
      <hour>23</hour>
      <minute>15</minute>
    </start>

    <daily>
      <all/>
    </daily>

  </time>

</frequency>

For information about its child elements, see <time> in the Parent Element column of this table.

 
<interval>

<interval unit="seconds">

<interval unit="minutes">

<interval unit="hours">

<interval unit="days">

(Conditional) Specifies the elapsed time between scheduled versions in seconds, minutes, hours, or days.

You must use one of the attributes in the Interval tag to specify the units of the integer value you specify as the interval of time to wait between when the versioning begins. For example, to specify an interval of 30 minutes:

<interval unit="minutes">30
</interval>

You must specify a non-zero value for the interval or the job cannot start. If no interval value is set, 0 (zero) is the default setting.

If no interval unit is set, seconds are the default unit setting.

Use either the Time element or Interval element, but not both in the same Job element. 

<time>

(Child to <frequency>)

 
<start>

Contains child elements that specify the hour and minutes that the job is scheduled to run on the specified days of the week.

For information about its child elements, see <start> in the Parent Element column of this table.

 
<daily>

Contains child elements that specify the days of the week that the job is scheduled to run. You must specify at least one day or the job cannot start.

For information about its child elements, see <daily>in the Parent Element column of this table.

 
<start>

(Child to <time>)

 
<hour>

Specifies the hour of the day that the job begins, based on a 24-hour clock. A valid hour entry is an integer value ranging from 0 to 23. For example, to set the hour to 10 p.m.:

<hour>22</hour>

If no hour is set, midnight (00) is the default hour setting.

 
<minute>

Specifies the minutes of the hour in the day that the job is scheduled to begin. A valid minutes entry is an integer value ranging from 0 to 59. For example, to set the minutes after the hour to 45 minutes:

<minute>45</minute>

If no minute value is set, zero (00) is the default minute setting.

 
<daily>

(Child to <time>)

 
<monday/>

<tuesday/>

<wednesday/>

<thursday/>

<friday/>

<saturday/>

<sunday/>

<all/>

Specify one or more of the child elements as the days of the week you want to schedule the versioning to occur. If no <daily> value is set, the job cannot start.

For example, to specify versioning to occur on Tuesday, Friday, and Sunday of each week:

<daily>
  <tuesday/>
  <friday/>
  <sunday/>
</daily>

Use the <all/> tag to specify all seven days of the week. For example:

<daily>
  <all/>
</daily>

Each of the <daily> child elements is an empty element; it has no child elements and no data values. 

<deletePolicy>

(Child to <defaults> and to <job>)

 
<maxKeepTime>

<maxKeepTime unit="seconds">

<maxKeepTime unit="minutes">

<maxKeepTime unit="hours">

<maxKeepTime unit="days">

<maxKeepTime keepCurrentCopy=
"true">

<maxKeepTime keepCurrentCopy=
"false">

Use one of the unit attribute values in the <maxKeepTime> tag to specify the units of the integer value you specify as maximum lifetime of a version.

If no maxKeepTime value is set, file versions are retained indefinitely.

If a value is specified without a unit attribute, “seconds” is the default unit of the value specified.

Use the keepCurrentCopy attribute to designate that at least one file version of current files remains in the database, even if the maxKeepTime elapses.

If keepCurrentCopy is set to True (default), the archive keeps an existing file version as long as its source file is current on the source volume, beyond the maxKeepTime. After the user deletes the current source file, the deletion is noted at the next scheduled epoch. If the file version’s age is within the maxKeepTime, the archive database retains a copy of the file version until its maxKeepTime elapses. When the file version’s age exceeds the maxKeepTime, the archive deletes the file version at the next scheduled delete time.

If keepCurrentCopy is set to False, the archive deletes a file version when it exceeds the maxKeepTime, even if the file version is the only one in the archive database for a given source file, and whether the source file is current or deleted.

The keepCurrentCopy attribute is optional. If the keepCurrentCopy attribute is not otherwise specified, the default value is True.

For example, to keep versions for 90 days before purging, to keep at least the most current version, and to schedule the purging of versions with 1-hour intervals:

<deletePolicy>

  <maxKeepTime unit="days"
    keepCurrentCopy="true">90
  </maxKeepTime>

  <interval unit="hours">1
  </interval>

</deletePolicy>

<deletePolicy>

(cont’d)

 
<maxKeepVersions>

Specifies the maximum number of versions of each file to keep in the archive. As the number of versions exceed this integer value, the oldest version is deleted.

For example, to keep up to 1000 versions of each file before purging and to schedule the purging of versions to begin at the default interval of 24 hours before the next scheduled versioning process:

<deletePolicy>

  <maxKeepVersions>1000
  </maxKeepVersions>

</deletePolicy>

<interval>

<interval unit="seconds">

<interval unit="minutes">

<interval unit="hours">

<interval unit="days">

The interval represents the amount of time to wait from the time a Delete process ends until another Delete process begins. If a value is not specified, 24 hours is the default delete policy interval. The time involved in deleting file versions varies with the amount of data stored in the archive server. The Delete Schedule operates separately from the Version Schedule.

For example, suppose you set the Delete Schedule to 2 days. When you activate the job, the Delete process begins. When it is done, it sets an interval timer. After two days elapse, the Delete process runs. The timer is inactive while the process runs. When the delete process ends, the interval timer begins again. The process repeats until the job is deactivated.

For example, to keep up to 100 versions of each file before purging and to schedule the purging of versions with a 2-hour interval:

<deletePolicy>

  <maxKeepVersions>100
  </maxKeepVersions>

  <interval unit="hours">2
  </interval>

</deletePolicy>

If an attribute is not specified for the <interval> tag, "seconds" is the default unit of the value specified.

If the <interval> element is not specified in either the Defaults element or the Job element, the default interval is 24 hours.