Nesstar Server Configuration Tool User Guide

Version 3.50

The Configuration Tool allows the server Administrator to edit most of the server configuration properties and to perform basic administrative operations such as starting/stopping the server.

Contents:

• Starting the Configuration Tool • Server Configuration - Simple mode

o License Code o Server Name o HTTP Port o IP address o Administrator Name o Administrator Password

• Server Configuration - Advanced mode • WebView Configuration • Configuring for Network Address Translation • Configuring for Web HTTP/Socks Proxy Web Server • Configuring with external Databases

o Common Configuration o MySQL o Sql Server 2000 o Oracle 9i/10g

• Configuring Web Services • Starting and Stopping the Server • Customising the Server and Nesstar WebView

o Customising the Server Homepage o Customising the WebView Header Source o Customising the Nesstar WebView Welcome Source o Customising the Nesstar WebView Footer Source o Customising the Nesstar WebView Catalogue Source

• Migrating Data from another Server • Creating a Server Customisation Bundle • Creating an Installation Customisation File • Installing a Server Customisation Bundle • Creating a Language Pack

o Customising an Existing Language File o Creating a New Language Pack

• Adding Users • Server Debugging

o Send Debugging Information o Action Recorder Tool

1

o Log Analysis Tool o Debug

• Tools o Xml Viewer o Registry Editor

• Help

Starting the Configuration Tool

The Configuration Tool is launched automatically after the Server is installed.

Afterwards it can be launched by:

• Windows Family: o Clicking on the shortcut located in Programs

-> Nesstar-Server-3.xx -> Configure o or by clicking on Configure in the Nesstar

Server installation directory. • Unix/Linux:

o Executing ./bin/configure.sh in the Nesstar Server installation directory.

When the tool opens you will be presented with the 'Simple' configuration screen.

Server Configuration - Simple mode

The 'simple' configuration mode allows settings to be established and changes made to the items listed below.

You can save any changes made to the configuration settings by using File -> Save Settings.

• Edit -> Undo Settings allows you to undo any changes in the configuration tool fields as long as any new entries have not been saved

• Edit -> Reset Settings allows you to restore settings to their defaults.

License Code

Enter your personal license code obtained from nesstar support. In order to change your code in future you may need to switch to Advanced Settings.

Server Name

Enter a name for the server in this field (the server name cannot contain spaces). This name will identify the server to external users. It is also used as the name for the default

2

catalogue in which datasets are published. Please note that the server name can be set up only once using the Configuration Tool. Please ensure therefore that the desired name is assigned to the server before completing installation.

HTTP Port

This is the port connection on which the Nesstar Server accepts connections. By default it is set to 80 but this may be changed if this port is already in use. For remote publishing port 80 is recommended to maximise access from organisations with restrictive firewalls.

IP address

This is the machine IP (or symbolic address) that your Nesstar Server will accept connections on. When you use the Nesstar WebView client you can view the published items on your server by entering the IP address and port number in your web browser. It is preferable to enter the complete symbolic address of the server machine (e.g. hostname.domain.co.uk) rather than a numeric IP address.

If you desire to run the server as a local server, not to be accessed by other machines, use the default local address localhost or 127.0.0.1.

Administrator Name

This field displays the administrator user name. This will be used as your user id when administering any Nesstar services.

Administrator Password

This is the password used with the server administrator user id and will be needed to access any of the functions that require special permissions.

Server Configuration - Advanced mode

The 'Advanced mode' of the configuration tool contains many additional settings for the Nesstar Server. Each setting is displayed with a short explanation. In most cases they do not need to changed and are best left in their default modes. Some settings can only be changed by 'Apply Settings'. Advanced settings may also be accessed using the Registry Editor.

WebView Configuration

3

The 'WebView configuration' screen of the configuration tool contains many additional settings for the WebView WWW Interface. To access this screen click on the button 'WebView settings'. Once modified, these settings can be applied by clicking on 'Save'. Currently reset of WebView settings is disabled. WebView settings may also be accessed using the Registry Editor.

Configuring for Network Address Translation

One case where you will need to modify the 'Advanced mode' settings is to configure your server to accept http connections on a different ip address (and/or port) from the local machine address (and/or port). This kind of setup is usually referred to as 'Network Address Translation' or NAT for short.

To enable NAT you will need to specify the internal Pattern IP Address which resolves incoming addresses to the bind ip address. You do not need to change the bind ip or bind port, only the external ip and external port that are displayed under 'Simple mode'. To disable NAT simply change this value back to localhost. When disabled the internal ip and port are automatically synchronised to their respective external values.

The server decides which address to return to the user (internal or external) based on the remote users address and the pattern address. All configurable properties are listed below:

• IP Address = this is the externally visible machine ip (or host address) that your nesstar server will be accessed on.

• HTTP Port = this is the external port that your nesstar server will accept connections on.

• Bind IP Address = this is the machine bind ip (or host address) that your nesstar server will run on internally.

• Bind HTTP Port = this is the port that your nesstar server will bind connections on.

• Secure Port = this is the port that your secure nesstar server will run on if 'Secure Sockets' is set to true.

• Bind Secure Port = this is the port that your secure nesstar server will bind to if 'Secure Sockets' is set to true.

• Pattern IP Address=this is a pattern of internal ip addresses that will be resolved to the bind ip address.

Configuring for Web HTTP/Socks Proxy Web Server

4

Another case where you will need to modify the 'Advanced mode' settings is to configure your server to work through a web http or socks proxy web server. If you have a proxy server and do not configure these settings your nesstar server will not be able to function fully.

The server uses the proxy address to make http connections to itself both internally and from the client tools bundled with the server. All configurable properties are listed below:

• Web HTTP Proxy Host Address = the host address of your http proxy server if you access the web via a http proxy web server.

• Web HTTP Proxy Port = the port number that you use to access the http proxy web server.

• Web Socks Proxy Host Address = the host address of your socks proxy server if you access the web via a socks proxy web server.

• Web Socks Proxy Port = the port number that you use to access the proxy web server.

Configuring Web Services

Configuration of the web container is handled by the files server.xml and web.xml in the directory C:\Nesstar-Server\jboss\server\default\deploy\jbossweb-tomcat.sar (for unix use /usr/local/nesstar-server/jboss/server/default/deploy/jbossweb-tomcat.sar).

To enable directory browsing:

By default directory browsing is disabled. To enable browsing, in the file web.xml, change the parameter listings shown below as false to true:

<init-param> <param-name>listings</param-name> <param-value>false</param-value> </init-param>

A server reboot is necessary to make the change live. Comprehensive details on Tomcat configuration can be found at the Tomcat Documentation page.

Configuring with external Databases

Another case where you will need to modify the Advanced Mode settings is to configure your server to use an external database.

The server currently supports three standard database back ends: MySQL, Sql Server 2000 and Oracle. The default database MySQL is completely integrated into the server, so there is no need for further modifications if you use this

5

one. Alternatively, you may choose to run your server using either an Oracle or Sql Server 2000 database back end. The following describes the essentials for setting up your server to work with an alternative database.

Common Configuration

In the configuration tool you need to select the appropriate database (mysql/sqlserver/oracle) and adjust the Database Name, Jdbc User Name, Jdbc Password and finally adjust the Sql Server or Oracle Jdbc Url.

In the Jdbc Url shown below replace localhost with the actual IP (or host address) of the machine on which the database server is running on (if not running on the same machine as your nesstar server). E.g. replace localhost with nesstar.essex.ac.uk.

jdbc:microsoft:sqlserver://localhost:1433;SelectMethod=cursor;sendStringAsUnicode=true

You are advised to run the database and nesstar server on separate machines for best performance results.

For Oracle, note that in the Jdbc Url, nesstar refers to the Oracle 8.x Service Name (or SID in previous versions of Oracle).

jdbc:oracle:thin:@//localhost:1521/nesstar

The rest depends on the configuration of the external database itself with essentially the appropriate Database, User Name and Password. The following are very brief instructions of what to do and need to be carried out by an experienced database administrator.

MySQL

From your MySQL client enter the following SQL commands (replace text in bold with your personal settings):

CREATE DATABASE IF NOT EXISTS nesstar; GRANT ALL PRIVILEGES ON nesstar.* TO nesstar@localhost IDENTIFIED BY 'YourPassword';

Sql Server 2000

Launch the Sql Server Enterprise manager and create a new login (user) as the Jdbc User Name. Then create a new database as the Database Name and grant permissions to the user Jdbc User Name to access the Database Name. Remember to allow SQL Server authentication under the Security tab in the Properties (right click) of the database used for nesstar.

6

Oracle 9i/10g

Launch the Enterprise Manager Console and connect to the new database you created as the Database Name. Then inside the database tree create a new user as the Jdbc User Name with standard database administration privileges. Note that Oracle automatically creates a database Schema name which defaults to the Jdbc User Name during the database connection.

Technical issues with Oracle

• for multi-byte language support please make sure that your databases default Character Set is set up to use Unicode (AL32UTF8).

• the data type VARCHAR is restricted to 4000 bytes only.

• indexes cannot be created on varchars exceeding 3209 characters.

Starting and Stopping the Server

[Server ->Start | Restart | Stop]

Through the 'Server' menu at the top of the window it is possible to Start, Restart and Stop the Nesstar Server. This provides the user with a single location from which to control the basic server functions. Please note that Start will only start an integrated MySQL Server. Restart and Stop do not control the selected database server at all. This is also true of short-cuts and server bin batch files.

The default configuration installs and starts up both your nesstar server and MySQL server as Windows NT Services. You may disable either of these NT Services by setting their respective Server and MySQL NT Service properties to false under Advanced Settings. You may also set them up as either "manual" or "automatic" (the default) services by selecting the appropriate Service Mode. Manual does not start up the service once you have switched off the machine it is running on.

Customising the Server and Nesstar WebView

The Server configuration tool also allows the user to customise the appearance of the Server home page and the Nesstar WebView client. Details on how to customise each piece of information follow:

• To view the Server home page go to the top menu and select View -> Server Welcome Page.

7

• To view the Server object browser go to the top menu and select View -> Server Object Browser (see administrator guide for details).

• To view the Nesstar WebView client go to the top menu and select View -> WebView WWW Interface.

To edit the appearance of the Server and WebView client pages go to the top menu and select Customisation -> Customise

Once you have opened the page you wish to edit, select the 'HTML Source' button at the top of this screen to display a view that presents all the text and programming source code. All text that is not in a frame, i.e. not framed by text boxes, can be changed and new text added. Once you have completed any changes click on the 'Save' button. To view the changes refresh your web browser.

Click on the 'Preview' button to preview the web page in the same window or 'Open Externally' to view in your web browser.

Customising the Server Homepage

[Customisation -> Customise -> Server Welcome Source]

This allows you to edit the text that will appear on the server's home page. The default source is the following:

Welcome to the Nesstar Server • Access this server via the Nesstar WebView • Access the User Management Tool • Access to other Technical resources

Copyright © 2001-2006 - http://www.nesstar.com

Customising the WebView Header Source

[Customisation -> Customise -> WebView Header Source]

The default text is based on a pre-configured Nesstar WebView style sheet and appears as:

8

As this text appears at the head of every page, you may want to change this to include your company/organisation name and logo.

The code has been inserted into the 'HTML Source' dialogue window in the WebView header source.

To insert a logo first ensure that any icon, or logo, to be added is the appropriate size to fit the space in which it is intended.

To add a logo:

1. Make sure it is in .gif format. 2. Place file in the directory - :

C:\Nesstar-Server\jboss\server\default\deploy\root.war (for unix use /usr/local/nesstar-server/jboss/server/default/deploy/root.war)

3. Go to the configuration tool

4. Select the file in which to insert the image: File -> Open -> [file name]

5. When the dialogue window opens click the HTML Source button

6. The html tag you will need is the following: <img src="/PATH_RELATIVE_TO_ROOT"> - for example, if you have placed the icon in the base of the "root.war" directory the tag would look like this: <img src="/example.gif">

7. Please note that relative links such as <img src="example.gif"> written in static html files in the webview.war directory are relative to ".../deploy/webview.war/." and not ".../deploy/root.war/."

8. When you refresh the Nesstar WebView page in your web browser the icon should now appear.

Customising the Nesstar WebView Welcome Source

[Customisation -> Customise -> WebView Welcome Source]

The WebView Welcome source appears when Nesstar WebView is accessed via a web browser. It is displayed until a different Nesstar WebView function is chosen. For example, once a dataset is selected, corresponding information will appear in place of the welcome source.

9

The default source is the following:

This can be changed to provide your users with information about your particular Nesstar Server and the information they can obtain through it.

Customising the Nesstar WebView Footer Source

[Customisation -> Customise -> WebView Footer Source] It is also possible to provide information that will appear as a footer on all pages of Nesstar WebView. There is no default source for this but information about the support arrangements for your users could be included here. For example, possible text could be: 'Please report any problems to your server administrator, email: support@companyid.com'

Customising the Nesstar WebView Catalogue Source

[Customisation -> Customise -> WebView Catalogue Source]

The "WebView Catalogue source" is the text that is displayed when a user selects the server default catalogue in the Nesstar WebView.

The default source is:

The Support default catalogue.

10

You can edit this text to provide the user with useful information about the catalogue contents.

The text is in HTML format so you can also easily add links to your home page or to other sources of information.

The same text should also be displayed by other Nesstar clients whenever the user selects your catalogue.

The text is stored in the file ./config/catalog.html.

Migrating Data from another Server

[Customisation -> Migration Tool]

This tool is intended for importing the users, settings, customised web pages, catalogue tree and associated datasets deployed on a previous server to your new server. It requires that the new server and the old server both be running on the same machine. If the old server is not running, the migration facility will be unable to migrate users or the catalogue tree. Much of the process of migration is automated. However, in some cases it may be necessary to help the tool locate some of the files and directories it requires.

On starting the migration tool, you will be asked to “Select location of old Nesstar Server”. This is the directory that you specified when originally installing the server. Most commonly, this is C:\Nesstar-Server-3.xx (for unix /usr/local/nesstar-server-3.xxx). However, if you selected a different hard-drive or directory to install in, you will need to locate this. The tool should now list those data files and users which were present on your old server. Check which items you prefer to migrate. 'Server settings' refers to the settings displayed in advanced mode and 'Language Files' to the text files you can customise in Customisation -> Languages. The 'catalogue structure' refers to your old catalogue tree and the objects (e.g. studies or cubes) that it contained. 'ACU' refers to the users and 'Webpages' to either pages customised in the menu item Customisation -> Customise or added to root.war.

To complete the process, click ‘Migrate’ and the data should be copied to your new server data directory. Users will be imported to the server database and customised web pages copied into the relevant server web directory. You will need to wait until your server has completed deployment of the data files before seeing them in your nesstar client. You can watch the progress of this from your server welcome page.

Creating a Server Customisation Bundle

[Customisation -> Create Customisation Bundle]

11

This utility provides a way to distribute customisations and extensions to the basic server release in a simple zip file.

After selecting the command from the menu a panel is displayed that contains the options listed below. Checking an item will automatically transfer the selected file (or set of associated files) into the customisation bundle directory. The directory is located in ./config/bundles. You may add additional files directly into this directory before creating the bundle. The final bundle zip file is written to ./config/bundles/Nesstar-Update.zip. Note that if any checkbox labelled "Transfer" is not selected, this will not remove previously transferred files of that type from the bundles directory.

• Transfer my customised server web pages o Includes the Server Welcome Source and

Nesstar WebView Catalogue Source pages (if they have been customised) and any additional files placed in the web directory ./jboss/server/default/deploy/root.war.

• Transfer my customised webview pages o Includes the Nesstar WebView

Header/Welcome/Footer Source pages (if customised).

• Transfer my data files o Includes all micro data and metadata files

placed into the ./data directory. • Transfer my tree structure

o Includes all catalogue hierarchies, their descriptions and the objects that were contained within them.

• Transfer my users o Includes all users created in the User

Management Tool including their links to roles, agreements, projects and purposes.

• Transfer my custom code, forms and policy o Includes any extension code placed into the

./config/ext directory, all security forms placed in ./config/forms and your customised policy described within ./config/policy.acu.

• Include my configuration settings o Includes most of the settings which appear in

the configuration tool under advanced mode (paths are not included).

• No questions asked installation o Marks the customisation bundle to be auto-

installed once the configuration tool is launched (and once only) without asking for any configuration settings (such as passwords). These settings take on their default values (defined in ./config/server.properties).

• Overwrite existing bundle

12

o Will force any existing bundle zip file to be overwritten (otherwise the existing bundle zip is appended to).

After the bundle is created you are offered the option to save a copy of the bundle zip file in a convenient location. You may then distribute this bundle with a standard nesstar server release executable file and it will be automatically installed during the initial installation stage as long as it is in the same directory as the nesstar server executable file. Alternatively, it may be manually installed, as described in the next section.

Creating an Installation Customisation File

It is also possible to customise the installation program itself, i.e. the process before the configuration tool is launched. A simple nesstar.properties file is provided (in ./config/bundles) which - if present in the same directory as the nesstar server executable - overwrites the default behaviour of the installation program. Inside this file, there are several customisable settings such as 'installdir.name' which accept phrases and other such as 'startfolder.show' which accept boolean 'true' or 'false' values. Simply alter these settings to your preferred values and distribute this file with the standard release executable. If you do not wish to alter a setting, simply comment it out with a leading '#' symbol.

Installing a Server Customisation Bundle

[Customisation -> Install Customisation Bundle]

To manually install a nesstar customisation bundle, select the above menu and you will be prompted to select the bundle you wish to install. Click on 'Open' and the bundle will be transferred into your server ./config/updates directory. You may then choose to 'apply settings' immediately - in which case the bundle is immediately installed during the normal configuration sequence - or to postpone installation - in which case the bundle will be installed next time 'apply settings' is clicked or .\bin\install.bat executed (for unix ./bin/install.sh).

Creating a Language Pack

[Customisation -> Languages]

The language editor enables you to customise an existing language file or to create a new set. The Nesstar server comes pre-installed with English (and partial Norwegian) language support files. These can be viewed and edited in a

13

tree style browser. Each pack consists of a .properties file which is created and used by the server and it's counterpart .ansi file which is edited by the user and used to create the .properties file. The .properties file must be encoded in ISO-8859-1 (also known as Latin 1). The .ansi file must be encoded in the native encoding of the country, e.g. Cp1252 under Windows in the United Kingdom.

Customising an Existing Language File

To customise an existing language file simply select the file from the tree on the left side frame and type into the panel which will be populated on the right side frame. Click on Save when you have finished or Undo to set the text back to the last saved version. The original language files are stored in ./config/instdata/config/languages for easy restoring.

Creating a New Language Pack

To create a new language pack you must first copy all of the existing en properties files over to your required country code, e.g. for a French pack copy files ending in _en.properties to _fr.properties. These files are located in ./config/languages (server related) and ./jboss/server/default/deploy/webview.war/WEB-INF/classes/nesstar/webclient/translation (web client related). See ISO 639-2 to help determine your local 2 or 3 character country code. Then simply change the value of the first property from 'encoding = ISO-8859-1' to the encoding that you will be using to edit the file. Remove the entire line if you are not sure and the editor will use the local system's encoding. To start using the new pack you must now close and re-launch the Language Editor. The counterpart .ansi file containing your new language pack country code will be created automatically.

You can now edit the text directly in your chosen language using the Language tree Editor. Alternatively you may pass the .ansi files to a translator for translation. When editing the .ansi files externally please ensure that the editor supports the encoding that you have specified. In the same country, this is usually the system's default encoding anyway, so no change is needed. For example Greek uses an encoding of ISO-8859-7. Your system's locale can be viewed or modified in the Windows Control Panel under Regional and Language Options.

Adding Users

[Customisation -> Security -> User Management Tool]

The User Management Tool allows you to create and manage user accounts for your Nesstar Server.

14

To enter the User Management tool select Customisation -> Security -> User Management Tool, you will be directed to a page in your web browser. Enter your administrator user id and password (only administrators can update the user accounts).

The User Management Tool includes an online help facility.

Server Debugging

[Debugging -> Send Debugging Information]

The server has the added functionality of being able to send useful debugging information as an email directly to nesstar-support.

Configuration

To access this functionality you need to provide a reply email address and the email host details in the server configuration tool.

To be able to send a copy of the server log

1. Open the Configuration tool 2. Select advanced mode 3. Find the field Reply Email Address 4. Add the email address that you wish nesstar-support to reply to.

The next field that needs to be filled out is the Outgoing SMTP Mail host address.

Sending the file

To send the server log file

1. Open the Configuration Tool 2. Go to the top menu Debugging -> Send Debugging Information.

Please be aware that non-encrypted passwords will be contained in some of the information sent to us.

[Debugging -> Action Recorder Tool]

This tool is intended to help Nesstar diagnose problems found with web pages in the Nesstar Server. It allows users to produce a script of the actions taken in discovery of an issue, and Nesstar Support to follow these actions to reproduce the problem. When a bug is discovered in Nesstar WebView, or on any Nesstar Server web page, using this tool will allow you to create a script of your actions and

15

email it to Nesstar Support. Your server must be running before you start this tool.

[Debugging -> Log Analysis Tool]

This tool simply collates all server exceptions found in the server log file and lists them for easy perusal. To see the contents of an exception, select the item in the left frame and its contents will be displayed in the right frame.

[Debugging -> Switch Server Mode -> Debug]

This tool will restart your server in debug mode when selected. This opens a port which nesstar ltd. can then use for remote debugging. In order to alert nesstar to this, an email is automatically sent to the nesstar support team. Your server will remain in debug mode until either you explicitly switch back to Debugging -> Switch Server Mode -> Normal from the menu or when you next stop and start your server from either the configuration tool or the installation short-cuts.

Tools

[Tools -> Xml Viewer]

Use this function to check that the xml file you deploy is valid. The different parts of the DDI structure are presented in different folders comprising the various sectors of the DDI. The Nesstar Publisher allows the xml to be edited by making the DDI fields visible along with the data contained within them.

[Tools -> Registry Editor]

Use this function to browse and edit individual configuration settings in a tree style editor. All of the servers that have been installed on your system will be displayed in the tree with the name of the server at the top level and a message indicating whether the server is started or not running. Select a property or group of properties from the left side frame and it's value(s) will be displayed in the right side frame. If clicking on a folder all of the properties under that group will be summarised; if clicking on an individual leaf then that property is displayed in an editable component instead (only available for the server that you are running the configuration tool from). You may then edit this setting and click on OK to transfer the setting back to the main configuration screen. Alternatively click on Restore to set the value back to the last saved setting. Please note that settings are not saved permanently on disk until you click on Save Settings or Apply settings in the main screen of the configuration tool.

16

Help

For more technical assistance, or a greater level of detail about the Nesstar Server, please refer to the administrator guide available from the Help menu.

If you have any suggestions or questions please contact: Nesstar Support

Copyright © 2001-2006 NSD

17