Xythos Drive Configuration step-by-step Guide

Introduction

The document refers to the product as "Drive"; this is a development name for product distributed as Xythos Drive, Blackboard Drive and some others.

Configuration Files

The Drive uses the following configuration files (loaded in this order):

  1. Basic (mandatory, filename: xdconfig.xml)
  2. OS specific (mandatory, filenames: xdconfig_win.xml/xdconfig_mac.xml)
  3. Edition specific (mandatory, filename: xdconfig_edition.xml)
  4. OS and Edition specific (mandatory, filenames: xdconfig_edition_win.xml/xdconfig_edition_mac.xml)
  5. Customer (optional, filename: xdconfig_customer.xml)
  6. Administrator (optional, filename: xdconfig_admin.xml)
  7. User (optional, filename: xdconfig_user.xml)
Note: Some files are signed in the installed product to prevent unauthorized modification, in such case their extension is changed to *.xml.sig

All these files use the same tree structure in xml format. The full tree structure is defined in the Basic config file. All other files do not need to contain the whole structure, they can only contain the subtrees with values, that need to be changed in that config. If the respective config file template does not contain the subtree with value you need to change, you need to copy that subtree from the Basic config file.

Configuration Files Locations

Mac

File and Path Comments
 /Library/Application Support///configdata/xdconfig.xml.sig   master configuration file, signed, cannot be modified by a user 
 /Library/Application Support///configdata/xdconfig_edition.xml.sig   edition specific configuration file, signed, cannot be modified by a user 
 /Library/Application Support///configdata/xdconfig_mac.xml.sig   platform (system) specific configuration file, signed, cannot be modified by a user 
 /Library/Application Support///configdata/xdconfig_edition_mac.xml.sig   edition and system specific configuration file, signed, cannot be modified by a user 
 /Library/Application Support///configdata/xdconfig_customer.xml   customer configuration file used to change default package preferences according to customer's needs;  
  typically used to preset mass-config server; if no changes are required, the file may be missing  
  (both in the installation package and on the installed machine) 
 /Users//Library/Application Support///configdata/xdconfig_user.xml   contains user's preferences, e.g. volumes etc. 
 /Users//Library/Application Support///configdata/xdconfig_admin.xml   downloaded copy of the administrator-supplied config file distributed through the massconfig server 

Win

File and Path Comments
 c:\Users\AllUsers\\\configdata\xdconfig.xml.sig   master configuration file, signed, cannot be modified by a user 
 c:\Users\AllUsers\\\configdata\xdconfig_edition.xml.sig   edition specific configuration file, signed, cannot be modified by a user 
 c:\Users\AllUsers\\\configdata\xdconfig_win.xml.sig   platform (system) specific configuration file, signed, cannot be modified by a user 
 c:\Users\AllUsers\\\configdata\xdconfig_edition_win.xml.sig   edition and system specific configuration file, signed, cannot be modified by a user 
 c:\Users\AllUsers\\\configdata\xdconfig_customer.xml   customer configuration file used to change default package preferences according to customer's needs; 
 typically used to preset mass-config server; if no changes are required, the file may be missing 
 (both in the installation package and on the installed machine) 
 c:\Users\AllUsers\\\configdata\xdconfig_customer.xml.sample   contains a sample of customization for mass config settings 
 c:\Users\\AppData\Local\\\configdata\xdconfig_user.xml   contains user's preferences, e.g. volumes etc. 
 c:\Users\\AppData\Local\\\configdata\xdconfig_admin.xml   downloaded copy of the administrator-supplied config file distributed through the massconfig server 


Example 1: Local configuration of the installed Drive instance

This kind of configuration is not usable for mass configuration of Drive, but demonstrates how the configuration system works and is especially usable for validation of a config file before deploying it to users.

When you need to create any custom config file, no matter if you plan to customize an installation package for mass-deployment or post the config file on a server for a remote mass-configuration, make sure that the config file is valid by testing it on the already installed instance first, otherwise it might be difficult to isolate what went wrong.

Step 1

Install Drive, make sure it launches correctly.

Step 2

Quit Drive, make sure it is not running.

Step 3

Create a file with the following contents and name it "xdconfig_customer.xml":

xdconfig_customer.xml
<?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>
    <globalSettings>
      <massUpdateCurrentVersion>
        <gen:value>10</gen:value>
      </massUpdateCurrentVersion>
    </globalSettings>
    <usersSettings>
      lt;userList>
        <!-- by the folowing gen:updateListType we update template which is used for creating all user settings-->
        <gen:updateListType>
          <dirmanSettings>
            <cacheSettings>
              <cacheSize>
                <gen:value>123</gen:value>
              </cacheSize>
            </cacheSettings>
          </dirmanSettings>
        </gen:updateListType>
      </userList>
    </usersSettings>
  </xdConfig>
</gen:config>

Step 4

Copy the file to the xdconfig_customer.xml folder location as mentioned above, e.g. for the Drive on Mac to: /Library/Application Support/Xythos/Drive/configdata You need administrative privileges to copy the file to the config folder.

Step 5

Launch the Drive.

Result

You should now see the main Drive application window. Go to Preferences tab. The Cache Size should now show value 123 MB.

Troubleshooting

Drive failed to start:

The Cache Size does not show 123 MB:

Example 2: Create a customized installation package

In this example, we will create a modified installation package that will be preconfigured with a custom value of Drive cache size. This package can be then distributed to users; When a user installs this modified package, the manufacturer-default values will be overridden by the config values specified during the customization procedure.

Step 1

Create a file with the same contents as in Example 1 and name it "xdconfig_customer.xml".

When using the config file for package customization, the file can have any valid file name, because the customization procedure places the file inside the installation package with correct name, but for simplicity and to demonstrate that you can use the same file as in Example 1, keep the name "xdconfig_customer.xml".

Step 2

Create a new folder under your home folder and copy the "xdconfig_customer.xml" and the installation package, e.g. "XythosDrive-x64_1.7.16228" (for Windows) or "Xythos Drive 1.6.15324 .dmg" (for Mac). Although it should work most other folders, doing it as described here is a tested procedure and it will prevent potential problems with write permissions and collision with other files in the folder.

Step 3a (Mac)

Copy the admin scripts you received in the admin documentation in the distribution package, you will need at least "addcustomerconfig.sh" and "replaceconfig.sh". Make sure you have executable permissions for these scripts. You can run it under any account, but during the procedure the script will ask you for the admin access.

In Terminal, go to the folder you created for package customization and run the following command:

./addcustomerconfig.sh Xythos\ Drive\ 1.6.15324.dmg xdconfig_customer.xml

You should now see a new file in the current folder, "Xythos Drive 1.6.15324.dmg_customized.dmg".

Step 3b (Windows)

In the command line, go to the folder you created for package customization and run the following command:

XythosDrive-x64_1.7.16228_setup.exe /au xdconfig_customer.xml

You should now see a new file in the current folder, "XythosDrive-x64_1.7.16228_setup.new.exe".

Step 4

Install the newly create package and restart/logout if the installer asks you to do so.

Note for Windows: the installation package is signed with a certificate. If you customize a package and launch the installer, the User Account Control will show "Publisher: Unknown", but the installation should run normally. If you need the "Publisher" to show valid company name, ask Drive supplier to provide an unsigned package and instructions how to sign it with your certificate, because there seem to be technical limitations signing again an already signed package.

Result

You should now see the main Drive application window. Go to Preferences tab. The Cache Size should now show value 123 MB.

Troubleshooting

Drive failed to start:

The Cache Size does not show 123 MB:

Important notes

Example 3: Set up remote configuration of the installed Drive instance

In this example, similarly to Example 1, we will add the config file to the existing (locally installed) instance. Although not usable in production, this way we avoid potential problems with incorrect package customization or installation.

This time, instead of changing the cache size using local config, we will set the link to remote configuration file, and the remote config file will contain the modified cache size.

Step 1

Install Drive, make sure it launches correctly.

Step 2

Quit Drive, make sure it is not running.

Step 3

Take the file xdconfig_customer.xml created in Example 1, rename it to admin-config.xml

Step 4

Put the file admin-config.xml to a webdav server, e.g. to "http://wfs72sp5:8080/testuser1/admin-config.xml". Set the file permissions so that the file has public access, i.e. readable without username/password.

Step 5

Create a file with the following contents and name it "update-info.xml":

update-info.xml
<?xml version="1.0" encoding="UTF-8"?>
<root>
   <!--xd-update - the tag for information about updating Drive application
     NOTE: xd-update tag must be present even if you do not plan to update the Drive executable. Leave the version to be 0
     and location some valid (but non-existing) url.
     The necessity of presence of the tag is due to a bug in parsing of this file,
     which would cause error dialog to be shown during startup of Drive.
   -->
   <xd-update>
     <latest-version>
         <version>0</version>
         <location>http://wfs72sp5:8080/non-existing.dmg</location>
     </latest-version>
  </xd-update>

  <!--config-update - the tag for information about updating the config tree by admin config -->
  <config-update>
     <!-- version of the admin config at the url in location tag -->
     <massUpdateCurrentVersion>10</massUpdateCurrentVersion>
     <!-- url of a new version of admin config-->
     <location>http://wfs72sp5:8080/testuser1/admin-config.xml</location>
  </config-update>
</root>
Step 6

Put the file update-info.xml to a webdav server, e.g. to "http://wfs72sp5:8080/testuser1/update-info.xml". Set the file permissions so that the file has public access, i.e. readable without username/password.

Step 7

Create a file with the following contents and name it "xdconfig_customer.xml":

xdconfig_customer.xml
<?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>
      <globalSettings>
          <massUpdateUrl>
              <gen:value>http://wfs72sp5:8080/testuser1/update-info.xml</gen:value>
          </massUpdateUrl>
      </globalSettings>
  </xdConfig>
</gen:config>
Step 8

Copy the file to the xdconfig_customer.xml folder location as mentioned above, e.g. for Xythos Drive on Mac to: /Library/Application Support/Xythos/Drive/configdata

You need administrative privileges to copy the file to the config folder.

Step 9

Launch Drive.You should now see the main Drive application window. Go to Preferences tab. The Cache Size should now show value 123 MB. Quit Drive.

Step 10

Modify the update-info.xml on the server: change massUpdateCurrentVersion value to 11.

Step 11

Modify the admin-config.xml on the server: change massUpdateCurrentVersion value to 11. Change cacheSize value to 456

Result

Launch Drive.You should now see the main Drive application window. Go to Preferences tab. The Cache Size should now show value 456 MB.

Important notes
Troubleshooting:

Drive failed to start:

The Cache Size does not show 456 MB:

Example 4: Create a customized installation package preconfigured for remote configuration

This example is a combination of Example 1 and Example 2: We will create a customized installation package, that contains link to the remote configuration files, so when a configuration file on the server changes, the changes will be downloaded to the user's computer.

Step 1

Follow steps 3-7 from Example 3.

Step 2

Follow steps 2-4 from Example 2

Result

You should now see the main Drive application window. Go to Preferences tab. The Cache Size should now show value 123 MB.

Troubleshooting

Drive failed to start:

The Cache Size does not show 123 MB:

Important notes

Example 5: Create a customized installation package with remote configuration and auto-update

In this example, we will assume knowledge of how to check the validity of config files, so we will skip the check of the config file on a locally installed Drive instance and rather directly create the customized installation package.

Step 1

Create a file with the following contents and name it "xdconfig_customer.xml" (same as in Example 3):

xdconfig_customer.xml
<?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>
      <globalSettings>
          <massUpdateUrl>
              <gen:value>http://wfs72sp5:8080/testuser1/update-info.xml</gen:value>
          </massUpdateUrl>
      </globalSettings>
  </xdConfig>
</gen:config>
Step 2

Follow steps 2-4 from Example 2 to create the customized package.

Step 3

Similarly as in Step 2 above, take a newer build Xythos Drive 1.6.15456 and create the customized package Xythos Drive 1.6.15456.dmg_customized.dmg. You should now have two customized packages, Xythos Drive 1.6.15456.dmg_customized.dmg and Xythos Drive 1.6.15324.dmg_customized.dmg, both contain the same xdconfig_customer.xml from Step 1.

Step 4

Take the file xdconfig_customer.xml created in Example 1, rename it to admin-config.xml

Step 5

Put the file admin-config.xml to a webdav server, e.g. to "http://wfs72sp5:8080/testuser1/admin-config.xml". Set the file permissions so that the file has public access, i.e. readable without username/password.

Step 6

Take a newer build of Drive, e.g. "Xythos Drive 1.6.15324.dmg_customized.dmg" and upload it e.g. to "http://wfs72sp6:8080/testuser1" folder, so the url of the new version would be "http://wfs72sp6:8080/testuser1/Xythos%20Drive%201.6.153246.dmg_customized.dmg". Note that you must use the encoded path of the Drive build in the config xml file and the location of the build on the server must match the location in the <location> tags in update-info.xml. Change the value of <version> to match the new version of the Drive installation package. Set the file permissions so that the file has public access, i.e. readable without username/password.

Step 7

Create a file with the following contents and name it "update-info.xml":

update-info.xml
<?xml version="1.0" encoding="UTF-8"?>
<root>
   <!--xd-update - the tag for information about updating Drive application -->
   <xd-update>
     <latest-version>
             <!-- optional flag, if present, the user is not asked if he wants install the update -->
             <!-- the installation is started automatically -->
         <force-install/>
             <!-- optional flag, if present, the result of the comparison of versions of Drive during auto-update checking is inverted -->
         <force-downgrade/>
         <version>1.6.15324</version>
         <location>http://wfs72sp6:8080/testuser1/Xythos%20Drive%201.6.15324.dmg_customized.dmg</location>
     </latest-version>
  </xd-update>

  <!--config-update - the tag for information about updating the config tree by admin config -->
  <config-update>
     <!-- version of the admin config at the url in location tag -->
     <massUpdateCurrentVersion>10</massUpdateCurrentVersion>
     <!-- url of a new version of admin config-->
     <location>http://wfs72sp5:8080/testuser1/admin-config.xml</location>
  </config-update>
</root>
Step 8

Put the file update-info.xml to a webdav server, e.g. to "http://wfs72sp5:8080/testuser1/update-info.xml". Set the file permissions so that the file has public access, i.e. readable without username/password.

Result

The Drive starts and shows a message box that it will update to a newer version. Confirm the update and follow instructions to install and logout/restart. After the procedure is finished, you should see the main Drive application window. Go to Preferences tab. The Cache Size should now show value 123 MB.

Notes

  1. The files xdconfig_customer.xml and admin-config.xml follow the same syntax, because they are parts of the same config tree. They have different names in examples above to emphasize how the file will be used, but as you can see above, e.g. to change cache size, you use the file with the same contents, no matter if you add it to the Drive config chain by copying to an installed instance, through package customization or through remote config, the only difference is how the file is distributed.
  2. When the remote configuration file is successfully downloaded to the client machine, it is locally stored as xdconfig_admin.xml in a location mentioned above.
  3. The installation package on the server used for the auto-update of the application needs to be customized with the link to the update-info.xml, otherwise the upgraded application will lose the remote update functionality.