Xythos Drive Configuration step-by-step Guide
The document refers to the product as "Drive"; this is a development name for product distributed as Xythos Drive, Blackboard Drive and some others.
The Drive uses the following configuration files (loaded in this order):
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.
File and Path | Comments |
---|---|
/Library/Application Support/ |
master configuration file, signed, cannot be modified by a user |
/Library/Application Support/ |
edition specific configuration file, signed, cannot be modified by a user |
/Library/Application Support/ |
platform (system) specific configuration file, signed, cannot be modified by a user |
/Library/Application Support/ |
edition and system specific configuration file, signed, cannot be modified by a user |
/Library/Application Support/ |
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/ |
contains user's preferences, e.g. volumes etc. |
/Users/ |
downloaded copy of the administrator-supplied config file distributed through the massconfig server |
File and Path | Comments |
---|---|
c:\Users\AllUsers\ |
master configuration file, signed, cannot be modified by a user |
c:\Users\AllUsers\ |
edition specific configuration file, signed, cannot be modified by a user |
c:\Users\AllUsers\ |
platform (system) specific configuration file, signed, cannot be modified by a user |
c:\Users\AllUsers\ |
edition and system specific configuration file, signed, cannot be modified by a user |
c:\Users\AllUsers\ |
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\ |
contains a sample of customization for mass config settings |
c:\Users\ |
contains user's preferences, e.g. volumes etc. |
c:\Users\ |
downloaded copy of the administrator-supplied config file distributed through the massconfig server |
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.
Install Drive, make sure it launches correctly.
Quit Drive, make sure it is not running.
Create a file with the following contents and name it "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>
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.
Launch the Drive.
You should now see the main Drive application window. Go to Preferences tab. The Cache Size should now show value 123 MB.
Drive failed to start:
The Cache Size does not show 123 MB:
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.
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".
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.
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".
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".
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.
You should now see the main Drive application window. Go to Preferences tab. The Cache Size should now show value 123 MB.
Drive failed to start:
The Cache Size does not show 123 MB:
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.
Install Drive, make sure it launches correctly.
Quit Drive, make sure it is not running.
Take the file xdconfig_customer.xml created in Example 1, rename it to admin-config.xml
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.
Create a file with the following contents and name it "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>
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.
Create a file with the following contents and name it "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>
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.
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.
Modify the update-info.xml on the server: change massUpdateCurrentVersion value to 11.
Modify the admin-config.xml on the server: change massUpdateCurrentVersion value to 11. Change cacheSize value to 456
Launch Drive.You should now see the main Drive application window. Go to Preferences tab. The Cache Size should now show value 456 MB.
Drive failed to start:
The Cache Size does not show 456 MB:
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.
Follow steps 3-7 from Example 3.
Follow steps 2-4 from Example 2
You should now see the main Drive application window. Go to Preferences tab. The Cache Size should now show value 123 MB.
Drive failed to start:
The Cache Size does not show 123 MB:
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.
Create a file with the following contents and name it "xdconfig_customer.xml" (same as in Example 3):
<?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>
Follow steps 2-4 from Example 2 to create the customized package.
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.
Take the file xdconfig_customer.xml created in Example 1, rename it to admin-config.xml
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.
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.
Create a file with the following contents and name it "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>
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.
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.