Skip to main content
pdf?stylesheet=default
Blackboard Help

Mass Configuration for Mac

This administrator guide provides instructions and information for running the Blackboard Drive for Mass Configuration (Mass Config) utility. The Mass Config is used for configuration of Blackboard Drive installations for the end users. For example, the Mass Config can create a new Volume for the end user and specify what Drive letter this Volume should use. It can also be used to set various other options such as cache size.

Blackboard Drive Configuration Files

When it starts, Blackboard Drive loads its internal configuration files. It next looks for and, if necessary, loads an administrator-configured file. This file is downloaded from a URL specified by administrator.

View and download admin-config-sample.xml to use as the template for your admin-config.xml file. Either create a copy of the file and name it admin-config.xml, or create a new file named admin-config.xml.

When using the Auto-Update feature, the xdconfig_customer.xml calls out to the server's update-info.xml file, which contains versioning information for the admin-config.xml file. If the version information has been updated, the admin-config.xml file will be called, and the new values will be brought to the user's system via auto-update. The configuration file for Mass Config is named admin-config.xml. See the table in Description of Configurable Attributes section (below) for parameter settings and syntax.

Preventing a User from Overriding the Value

For some parameters, you may need to prevent a user from overriding it. This is done on a per attribute basis by the presence of the gen:locks="edit" attribute in the configuration file.

For example, to set the server to https://as91sp6 and prevent the user from updating this value, the configuration file would include a definition like the following:

<server gen:locks="edit">
  <gen:value>https://as91sp6</gen:value>
</server>

Description of Configurable Attributes

The following table provides the list of attributes that can be configured via the Mass Configuration utility, and provides details on the type of data and the possible and default values.

How to read the table:

  • The Name column lists how the item must be referenced in the configuration file.
  • The Description cell describes what the parameter is used for.
  • The Default value is the value that is used if none is specified.
Configurable Attributes
Name massUpdateCurrentVersion
Description The value of this item is used by the auto-update feature to determine whether a new version of the configuration file needs to be retrieved from a mass-configuration server. When the massUpdateCurrentVersion in the config file on the remote mass-config server is higher that the massUpdateCurrentVersion in the local admin config, the remote config file is downloaded and applied. See Auto-update and Versioning for detailed description of how the mass-config system works.
Type string
Default Value 0
Example

<massUpdateCurrentVersion>
    <gen:value>10</gen:value>
</massUpdateCurrentVersion>

Lock Level none
Name userList
Description The template which creates all user settings is updated through gen:updateListType.
Type  
Default Value none
Name userCacheDir
Description It is the path to the directory where user cache files are placed. For this path customization you can use macros as is described in Usage of macros in config
Type expstring
Default Value %LOCAL_APPLICATION_DATA%/%SHORT_COMPANY_FOLDER%/%PRODUCT_FOLDER%/cache/
Example Mac OSX /Users/<username>/Library/Application Support/<Short Company name>/<Short Product name>/cache
Lock Level none
Name userDataDir
Description The location which will be used for data storing during disaster recovery. The default location is user home. For this path customization, you can use macros as is described in Usage of macros in config
Type expstring
Default Value %USER_HOME%
Example Mac OSX /Users/<username>/
Lock Level None
Name proxyList
Description List of user proxies. By default the list contains only one MainProxy only. Currently Blackboard Drive is able to operate with one proxy and does not give a user chance to maintain more of them. This is likely to change in future releases.
Type  
Default Value <gen:updateElement gen:templateguid="Xythos;15:03:08 14:14:46 +0100;Xythos;15:03:08 14:14:46 +0100;MainProxy">
Name MainProxy
Description Currently XD is able to operate only with one proxy and does not give user chance to maintain more of them. The setting of this main proxy ("MainProxy") is created according to "proxySettings (template)" and contains following items:

proxyUsage

proxyServer

proxyPort

proxyUsername

proxyPassword

Type proxySettings (template)
Guid XythosXythos;15:03:08 14:14:46 +0100;MainProxy
Values

proxyUsage - "DONT_USE_PROXY", not locked

proxyServer - "", not locked

proxyPort - 8080, not locked

proxyUsername - "", not locked

proxyPassword - "", not locked

Name proxyUsage
Description This value decides if this proxy will be used or not. Possible values are:

DONT_USE_PROXY - no proxy will be used

USE_PROXY - use this proxy with its settings

AUTO_DETECT - auto-detect the proxy (from system) and use just username and pwd.

Type enum
Default Value DONT_USE_PROXY
Lock Level None
Name proxyServer
Description The URL of proxy server without port.
Type string
Default Value none
Name proxyPort
Description The port of proxy server. It has to be from the correct port range.
Type integer
Default Value 8080
Lock Level none
Name volumeList
Description List of all users' volumes.
Type  
Default Value  
Name updateListType
Description The template which creates all volumes is updated through gen:updateListType.
Type  
Default Value <gen:updateListType>
Name sharingLevel
Description The sharing level that should be used for this volume.
Possible values:

None

Light

Medium

Heavy

(or name of any new sharing level created by administrator).

Type string
Default Value Heavy
Name username
Description Name of a user used to authenticate against remote server.
Type string
Default Value none
Lock Level none
Name server
Description The url of server where the volume should be connected. It must be valid URL.
Type string
Default Value none
Lock Level none
Name serverUrlCustomerConstraint
Description The server volume constraint where the volume should be connected. Represented as regular expression.
Type string
Default Value none
Lock Level none
Name name
Description The name of a volume. It is mandatory for a volume to have a unique name.

The name must match the following regex pattern: [a-zA-Z_0-9]+[a-zA-Z_0-9-:\.]*

Type string
Default Value none
Name bypassProxy
Description If true, the proxy will not be used for the connection of this volume to remote server (even if otherwise the proxy is used).
Type boolean
Default Value false
Lock Level none
Name autoConnectAfterStart
Description Tells the Drive if this volume should be automatically connected after start.

Possible values:

DISCONNECTED - default value, the volume stays disconnected

ONLINE - the volume will be connected.

Type enum
Default Value DISCONNECTED
Lock Level none
Name openFileManagerUponConnection
Description If true, the default file manager window will be opened immediately after connection of the volume.
Type boolean
Default Value false
Lock Level none
Name lockTimeout
Description Time in seconds, after which the autolock on a file on the server expires. The value is sent to the server when locking a file. Note that WebDAV server may not respect this value and may use its own preferred value.
Type longnum
Default Value 900
Lock Level edition
Name refreshPeriod
Description The time in seconds after which the autolock is refreshed if a document is still opened.
Type longnum
Default Value 300
Lock Level none
Name unblockFileAfterAppCloseTimeout
Description The time after which the file is considered to be really closed, measured since closure of the application used to edit the file.
Type longnum
Default Value 3
Lock Level none
Name normalUnlockDelay
Description The time after which the file is considered to be really closed. Measured since the close which makes the open count on the file equal zero. Applicable only to the processes not listed in appsThatKeepFileClosed list. For example, after this timeout file is auto-unlocked.
Type longnum
Default Value 5
Lock Level none
Name appsThatKeepFileClosedWhileEditing
Description A list of process names, which does not keep file opened during editing. The list helps to decide e.g. when to auto-unlock the opened file - such file cannot be unlocked after last fs close, but we have to wait for closing the whole application.

You can add processes which are known to behave as described. For example, if you want to add notepad++ application because it is known it does not keep file opened during editing, you can do it like this:

<appsThatKeepFileClosedWhileEditing>
  <gen:newElement gen:guid="notepad+.exe" gen:val="notepad+.exe"/>
</appsThatKeepFileClosedWhileEditing>

Type List
Default Value TextEdit, Preview, Pages, Keynote, Numbers
Lock Level none
Name neverLockList
Description A list of names of such processes, which will not autolock a file even if they open the file for writing. You can add new processes. For example if you want to add the file manager servant salamander, you can do it like this:

<neverLockList>
  <gen:newElement gen:guid="salamand.exe" gen:val="salamand.exe"/>
</neverLockList>

Type List
Default Value Finder, quicklookd, Preview, mv, cp
Lock Level none
Name alwaysLockList
Description A list of names of processes, for which autolocking will be invoked even if the file is opened only for read. You can add processes. For example, if you want to add application Notepad++ because it is known it does not keep file opened during editing, you can do it like this:

<alwaysLockList>
  <gen:newElement gen:guid="notepad+.exe" gen:val="notepad+.exe"/>
</alwaysLockList>

Type List
Default Value TextEdit, Microsoft Word, Microsoft Excel, Microsoft PowerP, Pages, Keynote, Numbers
Name normalUnlockDelay
Description The time after which the file is considered to be really closed, measured since the close which makes the open count on the file equal zero. Applicable only to the processes which are not listed in appsThatKeepFileClosed list. For example, after this timeout file is auto-unlocked.
Type longnum
Default Value 5
Name disabledApplications
Description List of applications for which the filter is disabled. If enabledApplications is defined then the filter will be used
just with these apps. If disabledApplications is defined, the filter will be used for all applications excluding these.

You can add the processes:

<disabledApplications>
  <gen:newElement gen:guid="notepad.exe" gen:val="notepad.exe"/>
</disabledApplications>

Type list
Default Value none
Lock Level none
Name enabledApplications
Description List of applications for which the filter is enabled. If enabledApplications is defined then the filter will be used just with these apps. If disabledApplications is defined, the filter will be used for all applications excluding these.

You can add processes :

<enabledApplications>
   <gen:newElement gen:guid="notepad.exe" gen:val="notepad.exe"/>
</enabledApplications>

Type List
Default Value none
Lock Level none
Name connectTimeout
Description Determines the timeout until a connection is established. A timeout value of zero is interpreted as an infinite timeout. If this parameter is not set, connect operations will not time out (infinite timeout).
Type integer
Default Value 10
Name defaultMethodTimeout
Description

Defines default socket timeout for methods (SO_TIMEOUT), which is the timeout for waiting for data or, put differently, a maximum period inactivity between two consecutive data packets. A timeout value of zero is interpreted as an infinite timeout. If this parameter is not set, operations will not time out (infinite timeout).

This value will be applied to all methods except those which have their explicit values listed in MethodTimeoutsList.
In seconds.

Example of setting default method timeout to 100 seconds:

...
<defaultMethodTimeout>
   <gen:value>100</gen:value>
</defaultMethodTimeout>
...

Type integer
Default Value 30
Name pruningMinimalTimeout
Description Minimal time after which XD cache pruning is started after previous pruning. In minutes.
Type string
Default Value 15
Name cacheSize
Description Maximum cache size in megabytes (MB). The cache size can be temporarily greater than the value set here - for example, due to working with a large file, which size is greater than the cacheSize. Note that the small cache size (which often leads to cache pruning) may result in very bad user experience.
Type integer
Default Value 512
Name clearCacheOnServerDisconnect
Description If set to true, the cache from a server is cleared after disconnection from the server.
Type boolean
Default Value false
Name alwaysLocalFilesList
Description List of regular expressions. If a filename matches one of the expressions in this list, the file is considered to be local (is not uploaded).

You can add new regular expressions:

<alwaysLocalFilesList>
  <gen:newElement gen:guid="mytmp" gen:val=".*\.mytmp"/>
</alwaysLocalFilesList>

Type list
Default Value There are 2 default values:"(\.[^\.]*|\.\..+))" and "\.DS_Store"
Name notificationWindowPopupTime
Description This item defines lifetime of certain notification dialogs in seconds.
Type integer
Default Value 30
Name helpPageURL
Description The URL of Blackboard Drive help page.
Type string
Default Value Depends on the edition.
Name checkBeforeOpen
Description Tells Blackboard Drive if a file should be checked for any recent change before open (by means of PROPFIND method). If Blackboard Drive finds out that the file was changed on server and the file contents in cache is stale, new download is issued.
Type string
Default Value Depends on the edition.
Name cachedListings
Description If true and directory contents was cached, remote dirlist is not done.
Type boolean
Default Value false
Name refreshTimeout
Description Time in milliseconds. Tells Blackboard Drive after how much time is cached dirlist or remote attributes considered out of date. The Drive does not need to honor this value. It serves as a hint.
Type integer
Default Value 0
Name DisableRemoteAttributesAddition
Description Disables adding of new file or folder remote attributes (for example, WebDAV properties) in Properties dialog. Modification or deletion of existing attributes is unaffected.
Type boolean
Default Value false
Name DisableRemoteAttributesModification
Description Disables modifying existing file or folder remote attributes (for example, WebDav properties) values in Properties dialog. Adding or deletion of attributes is unaffected.
Type boolean
Default Value false
Name DisableRemoteAttributesDeletion
Description Disables deleting existing file or folder remote attributes (for example, WebDAV properties) in Properties dialog. Adding or modification of attributes is unaffected.
Type boolean
Default Value false
Name javaSecurityAuthLoginConfig
Description Allows to setup java system property java.security.auth.login.config for SPNEGO/KerberosV5 (Negotiate/KerberosV5) HTTP authentication. The value determines the location of login config file. The file must contain the configuration section named as com.xythos.client.http.auth.mac.NegotiateScheme. This file is not installed by XD for Mac Installer. This file is supposed to be distributed to the client machines by an administrator through 3-rd party tool or manually. Blackboard Drive for Mac has to be restarted to accept the file that has just been placed. This is Mac OS X platform specific option.
Type string
Default Value /Library/Preferences/Blackboard/Drive/auth-config/login.conf
Lock Level delete, edit
Example com.xythos.client.http.auth.mac.NegotiateScheme {
  com.sun.security.auth.module.Krb5LoginModule required useTicketCache=true renewTGT=true debug=true;
};
Name javaSecurityKrb5Conf
Description Allows to setup java system property java.security.krb5.conf for SPNEGO/KerberosV5 (Negotiate/KerberosV5) HTTP authentication. The value determines the location of kerberos V5 config file. The file contains Kerberos configuration. The information includes mapping between domains and realms and Key Distribution Center host name for each realm. This file is not installed by Blackboard Drive for Mac Installer. This file is supposed to be distributed to the client machines by an administrator through 3-rd party tool (e.g. Apple Remote Desktop) or manually. The Blackboard Drive for Mac must be restarted to accept just placed file. This is Mac OS X platform specific option.
Type string
Default Value /Library/Preferences/Blackboard/Drive/auth-config/krb5.conf
Lock Level delete,edit
Example

[libdefaults]
    default_tkt_enctypes = aes256-cts aes128-cts rc4-hmac des3-cbc-sha1
    default_tgs_enctypes = aes256-cts aes128-cts rc4-hmac des3-cbc-sha1
    permitted_enctypes   = aes256-cts aes128-cts rc4-hmac des3-cbc-sha1


[realms]
       TEST1.BRNO.LOCAL = {
         kdc = dc.test1.brno.local
         default_domain = TEST1.BRNO.LOCAL
         }

        BRNO.LOCAL = {
          kdc = brno.local
          default_domain = BRNO.LOCAL
         }

[domain_realm]
    .TEST1.BRNO.LOCAL = TEST1.BRNO.LOCAL
    .BRNO.LOCAL = BRNO.LOCAL

Name logDirectory
Description It is the path to the directory where logs files are placed. For this path customization, you can use macros as described in Usage of macros in config
Type Expstring
Default Value %LOG%/%SHORT_COMPANY_FOLDER%/%PRODUCT_FOLDER%/
Lock Level None
Name cookiesPolicyURL
Description The value of this item is used as the URL to Privacy Center.
Type String
Default Value Edition dependent
Name disableCookiesPolicyInformationDisplay
Description The value of this item enables/disables displaying privacy information dialog containing cookies policy information at the startup. This dialog should be displayed on startup since new EU privacy law take effect in the EU on May 26, 2012, and it is related to the use of cookies. Users must receive detailed notice/info on cookies and their purpose.
Type Boolean
Default Value FALSE
Name massUpdateTimeout
Description The value of this item is used by the auto-update feature to determine how many seconds Blackboard Drive can wait for mass-configuration server while retrieving the configuration file. There are also fixed timeouts for establishing the connection and downloading the file. Both are set to 10 seconds and cannot be changed. The value in this configuration item sets maximal accumulated value for both actions. Minimum value is 1 second.
Type Integer
Default Value 10
Name DisableIntellittach
Description Enables or disables the Create Intellittach feature
Type Boolean
Default Value FALSE
Name DisableVersioning
Description Enables or disables the create Versioning feature
Type Boolean
Default Value FALSE
Name IntellittachType
Description Defines the default Intellittach type. The default type is selected in the Create Intellittach dialog by default.

Possible values: LINK - create links by default; TICKET - create tickets by default

Type String
Default Value Ticket
Name ShowIntellittachDialog
Description Disables or enables the Create Intellittach dialog. When set to false, the dialog is not displayed and the link or ticket is created according to default values.
Type Boolean
Default Value TRUE
Name refreshTimeout
Description Time since the last directory listing, after which is the cached directory listing or remote attributes considered out of date. Expiration of this timeout does not immediately trigger a request for a directory listing from the server - it only invalidates the cached listing, a new listing is retrieved only after any application requests it. It is treated as a preferred value, the Drive may not use this exact value.
Type Integer
Default Value 0
Name allowExtendedAttributes
Description If this flag is set to false, Blackboard Drive does not allow a standard way of using extended attributes (using Apple Single file format). The system is then forced to use Apple double file format, which helps to persist the extended attributes in the form of the "._" files. When the flag is set to true, the persisting of the extended attributes does not work - the extended attributes are preserved only for the current session.
Type boolean
Default Value TRUE
Lock Level None
Name DisableVersioningStateChange
Description Defines if the options Enable Versioning and Disable Versioning on a file will be available to the user.
Type boolean
Default Value FALSE
Lock Level None
Name DisableCheckoutStateChange
Description Defines if the options Check Out, Check In and Undo Check Out on a file will be available to the user.
Type boolean
Default Value FALSE
Lock Level None
Name DisableManualLockStateChange
Description Defines if the options Lock and Unlock on a file will be available to the user.
Type boolean
Default Value FALSE
Lock Level None
Name localConnectivityRecoveryTimeout
Description The timeout determines the maximum period for which the HTTP request might be postponed in case the local connectivity was lost. The local connectivity can be lost after resuming the computer from sleep mode or while switching between networks like Wi-Fi to Wi-Fi, Wi-Fi to Ethernet or Ethernet to Wi-Fi. Note that accidentally Java can cache negative DNS request for some period (by default 10 seconds: see the property sun.net.inetaddr.negative.ttl in java.security file) so this interval should be also taken into account.
Type integer
Default Value 30
Lock Level None
Since version 1.6 SP1

Usage of Macros in Config

Introduction

The configuration files allow customers to change paths such as the path to cache, etc. These paths need to be absolute, which makes it difficult to specify a path that would work for multiple users because the paths usually differ, for example, by a user name or a user home folder. To overcome this limitation, the Drive since version 1.6 allows usage of special values, macros.

Basic principles

Default macros list

Here is the list of default macros:

Macro value Macro value type (absolute path/single name) Macro name
%COMPANY_FOLDER% company folder single name
%SHORT_COMPANY_FOLDER% short company folder single name
%PRODUCT_FOLDER% product folder single name
%DOCUMENTS% folder to store user's documents, like "My Documents" absolute path
%APPLICATION_DATA% roamable application data absolute path
%LOCAL_APPLICATION_DATA% non-roamable application data absolute path
%COMMON_APPDATA% application data folder shared by all users absolute path
%DESKTOP% current user's desktop folder absolute path
%COMMON_DESKTOP% all users common desktop absolute path
%USER_HOME% current user's home folder absolute path
%TEMP% default temporary directory absolute path
%PROGRAM_FILES% program files directory absolute path
%COMMON_PROGRAM_FILES%   absolute path
%STARTUP%   absolute path
%COMMON_STARTUP%   absolute path
%LOG% default log folder absolute path
%USERS% folder with all users accounts absolute path
%USERNAME% current user name single name

System environment variables

Besides the macros described above, it is possible to use all the system environment variables. All these variables have their macros formed by prefixing the name of the variable with SYSENV_ string. So for example, if we want to use the TMP system environment variable in the config, we can do so by using macro named SYSENV_TMP. Following the same pattern, one can use SYSENV_USERNAME macro for USERNAME variable, etc.

"gen:macros" attribute

The macros are expanded only if the node containing the value was enabled to use the macros. This can be done simply by adding xml attribute gen:macros (where gen is xml namespace "http://www.xythos.com/jconf/schema" as usual) to that particular xml node definition. The attribute can have either value "true" (to enable the expanding of macros) or "false" (to forbid the expanding). Moreover, the value has to be of the type STRING.

If you want to add or change a value containing a macro, you need to make sure the macro expanding is enabled for that value. If the value is not enabled in any higher-level config file, you need to add the gen:macros="true" next to the tag name, for example:

Enabling macro expansion when changing a value

...
<username gen:macros="true">
   <gen:value>%USERNAME%</gen:value>
</username>
...

Macro usage

Each macro starts and ends with "%" mark (as it can be seen in the table above in "Macro name" column). Currently, it is possible to use macros from the list above anywhere under user settings node in the config.

Escaping "%" character

If it is necessary to use the "%" character in the path, it needs to be escaped with another "%" character.

For example "/aaa/%%b" will be expanded to "/aaa/%b"

For example, a user wants to change logging directory using macro to user's desktop folder.

There is "logDirectory" element in "userSettings" node (it is of string type and has the expanding of attributes enabled by gen:macros attribute in the main config file xdconfig.xml).

Default logging directory on OS X

...
<logDirectory>
   <gen:value>C:\Documents and Settings\x\Local Settings\Temp\logs\Blackboard\Drive</gen:value>
</logDirectory>
...

Example of configuration file to change logging directory on Windows 7

We can change this default value to directory "logs" in user's desktop using macros in Blackboard Drive configuration file, for example xdconfig_customer.xml, like this.

<?xml version="1.0" encoding="UTF-8"?>
<gen:config xmlns:gen="http://www.xythos.com/jconf/schema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" gen:version="1">

  <xdConfig>
     <usersSettings>
       <userList>
         <gen:updateListType>
           <logDirectory>
             <gen:value>%DESKTOP%\xdlogs</gen:value>
           </logDirectory>
         </gen:updateListType>
       </userList>
    </usersSettings>
  </xdConfig>
</gen:config>

Example of configuration file to change logging directory on OS X

<?xml version="1.0" encoding="UTF-8"?>
<gen:config xmlns:gen="http://www.xythos.com/jconf/schema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" gen:version="1">

  <xdConfig>
     <usersSettings>
       <userList>
         <gen:updateListType>
           <logDirectory>
             <gen:value>%DESKTOP%/xdlogs</gen:value>
           </logDirectory>
         </gen:updateListType>
       </userList>
    </usersSettings>
  </xdConfig>
</gen:config>

When value of "logDirectory" is read at Blackboard Drive startup, the %DESKTOP% is expanded to user's desktop directory, e.g. "c:\Users\x\Desktop" on Windows 7 or "/Users/x/Desktop" on OS X, resulting in "c:\Users\x\Desktop\xdlogs" or "/Users/x/Desktop/xdlogs" respectively.