Running Greenstone

OK, I've installed Greenstone. Now how do I make it go?
If you're using the Windows local library you should be able to simply select "Greenstone Digital Library" from within the programs in your start menu.

If you're using the web library things are a little less obvious however. First make sure your webserver is configured correctly and is running (see the Greenstone Installer's Guide and your webserver's documentation for details). You can then simply open your web browser and point it at the URL of Greenstone's library executable. This is dependant on the way you configured Greenstone and your webserver. Typically it might be something like http://localhost/gsdl/cgi-bin/library.exe.

What web browser do I need to view Greenstone collections?
Greenstone relies on a web browser that supports tables, javascript, and in some places, frames. Any reasonably modern browser will do. Examples are Microsoft Internet Explorer 4, Netscape 4, and Mozilla. Newer releases of all these browsers will also work.

If you find that your favourite web browser does not work with Greenstone, please contact us.

''Note that there is an exception to the rule that any modern browser will do when running Greenstone. That is when you're using the restricted version of the Windows local library when you must use Netscape. See the discussion below on the differences between the "Restricted Version" and the standard "Enter Library" version of the local library for details''.

When I start the Windows local library there are two buttons in the dialog box, "Enter Library" and "Restricted Version". They both seem to do the same thing, what's the difference?
The webserver built into the local library uses the networking software built into your Windows operating system in order to function. If your computer has never been connected to a network this networking software may not be installed however. For this reason Greenstone comes with some networking software of it's own that it will use if it can't find any installed on your computer.

When you click the "Enter Library" button, Greenstone first checks to see if your computer has it's own networking software. If it does, it starts up using that, if not it starts up using it's own networking software.

When you click the "Restricted Version" button, Greenstone doesn't bother checking your system for networking software, it just goes ahead and uses it's own.

The catch is that there are several limitations with using the Greenstone supplied networking software. The most important limitations are that the local library won't be accessible from the network if run in this way (that is, it really will be "local" to the machine on which it's running) and that it must use a Netscape web browser. Using your computer's built-in networking software is therefore the prefered option.

So when should I use the "Restricted Version" of the local library?
Since Greenstone will automatically use it's own networking software if it can't find any installed on your computer it should not normally be necessary to run the "Restricted Version" explicitly.

Times when it may be necessary are.
 * If your computer's networking software has been installed incorrectly.
 * If Windows keeps attempting to dial up your internet service provider when you click the "Enter Library" button.

When I start the Windows local library my computer asks me to dial up my Internet Service Provider. Do I really need to be online to run Greenstone?
No you don't need to be online. This is caused by the webserver built into Greenstone's local library sending a message to your computer's networking software to make sure it's functioning correctly. On many Windows systems this causes the familiar dial up dialog box to appear. In most situations you can simply cancel the dialog box and (if required) press your browser's reload button to continue.

If this does not solve the problem, try starting the local library by clicking the "Restricted Version" button rather than the "Enter Library" button. See the discussion above on the differences between the standard and restricted versions of the local library for further details.

I'm trying to use the Windows local library. My web browser is starting up as expected but the Greenstone home page never gets loaded or gives an error message. What's wrong?

 * Check your web browser's internet proxy settings and turn proxies off (use Edit preferences on Netscape or Internet options on Explorer).
 * If Internet Explorer gives a message saying "The page cannot be displayed" and "Cannot find server or DNS error" at the bottom of the page, check in your network settings that your computer's name is set up correctly. For example, if there is a DNS suffix entered in your TCP/IP properties (in the Control Panel), make sure that your host name and suffix are correct for your computer. If the server is running correctly, you should be able to connect by visiting http://127.0.0.1/ in a web browser on the same machine that the local library is running on.

Where can I get more Greenstone collections?
Collections like those at www.nzdl.org will soon be made available for download.

When I attempt to access certain parts of Greenstone I'm asked for a username and password. What do I enter?
The initial username required here is admin.

If you installed Greenstone using the InstallShield installer on Windows or the Install.sh script on Unix you should have been asked to set a password during the installation procedure.

If you didn't, don't worry, the password defaults to being admin.

So if you don't know what to enter you should try username = admin, password = admin.

When I use the large query box function I occassionally get a Not Found error.
This may be caused by the URL becoming too long for your web browser. Because Greenstone currently stores all state information in the URL, if you do a search for a long phrase the URL can become very long. Different browser's on different platforms have different maximum URL lengths but in general it seems that Netscape can handle longer URLs than can Microsoft Internet Explorer.

There is very little you can do to avoid this problem with the way Greenstone is currently implemented (aside from not searching for long phrases). Future versions of Greenstone may store some state information on the server rather than in the URL but this has yet to be implemented.

How do I get usage information for my library?
You can enable usage logging by setting the logcgiargs option to true in greenstone/etc/main.cfg. This saves a log in greenstone/etc/usage.txt. The log entry is basically a list of cgi arguments. One entry is generated for each page request to the library.

You can find out what the cgi arguments mean by going to the Administration page of your Greenstone installation, or from this page.

Fix file permissions
The main problem when running Greenstone on Windows Vista is file permission settings. Vista has a different set of built-in users and default file permissions, especially for folders like Program Files.

In order to run Greenstone 2/3 on Windows Vista, it is important to NOT install it in Program Files. We recommend your 'User' directory as the installation destination, or perhaps your Documents folder.

This way Greenstone will be able to run without any extra steps.

Apply a GLI patch for Greenstone 2.80
The GLI shipped with Greenstone 2.80 does not run properly on Windows Vista if perl fails to read certain system settings. To fix this problem, delete or rename the existing GLI.jar file in the gli subdirectory of your Greenstone installation, then replace it with this patched GLI-2.80.jar (you will have to rename it to GLI.jar).

How do I fix a WSASYSNOTREADY error?
This error might occur if you have no network connection available, so there is no IP address for the server. When you run the Greenstone server, in the small window where you can start the library select File->Settings, and set the address resolution method to be "always use localhost" or "always use 127.0.0.1". Then (re)start the server.

Another possibility is that you are running an IIS server. This will probably be using port 80. Try changing the port number that the local library uses (to e.g. 8080), in File->Settings. Alternatively, try stopping the IIS server altogether and restarting the local library.

GS2.83 and onwards: What do I need to do if I want to move a Greenstone 2 installation?
For Linux, you will need to uninstall your Greenstone first and then reinstall it in the new location.

For Windows: In the case of GS2.83, if you move your Greenstone2 installation folder to some other location, make sure that you relocate it such that there are no spaces in its new path. For instance, "C:\Program Files\myfolder\greenstone2" contains a space between "Program" and "Files", which is not supported in version 2.83. In future versions of Greenstone, the spaces will not be a problem.

Once you've moved your Greenstone installation, there are a few further things to do to get it to work again:
 * 1) Open your Greenstone 2 installation's cgi-bin\gsdlsite.cfg file and change the value for the GSDLHOME property to reflect the new path to your Greenstone installation.
 * 2) To get the local library server (server.exe) to work from the new location: if your top-level Greenstone installation folder contains the files llssite.cfg and glisite.cfg, delete these. (Note that you should not delete the template files llssite.cfg.in and glisite.cfg.in!) If running the local library server has any issues with Internet Explorer, go to the local library's File>Settings menu and change the Other Browser setting to use Firefox.
 * 3) To get the apache web server included with Greenstone to work: delete the file lib\java\log4j.properties. (Doing so will ensure that if you execute the gs2-server.bat file--which launches the Greenstone Server Interface--this properties file will be regenerated with the correct value for gsdlhome.)

GLI's Preview Button can't successfully launch a web page in Firefox (or another web browser)
If you pressed the Preview Button in GLI and (firefox) browser launch fails with a message about not being able to launch a URL that looks almost right, except that firefox shows it to be prefixed with your GLI folder path, then you can try providing GLI with the full path to Firefox. This happened to someone working with GLI and Firefox on an Ubuntu.

/full/path/to/your/firefox %1
 * In GLI, go to File > Preferences > Connection and set the Preview Command field to:

which firefox
 * On Linux, to find the full path to where your Firefox is installed, you'd open a terminal and run:

For example, in my case, running the which command above returns: /usr/bin/firefox

I would therefore set my Preview Command field to contain: /usr/bin/firefox %1


 * Now quit GLI.
 * Restart it.
 * Try the preview button again.

I've lost my username and password, what can I do?
(With instructions by Diego Spano.)

User account details are stored in etc/users.gdb.

There are several ways in which to reset your admin account's password. If you have the admin account's authentication details, you can reset the password for other users.

Option 1

In greenstone/bin/script you have a perl script called "csv-usernames-to-db.pl". This program converts username details (password, group information etc) into the format used by Greenstone, and stores them in etc/users.gdb.

Do the following:

1. Create a text file named myusers.csv and add the following line inside: Tom,123456,administrator

2. open a terminal

3. move to Greenstone root folder.

4. Run setup.bat (Windows) or setup.bash

5. Run "perl -S csv-usernames-to-db.pl /path_to_file/myusers.csv"

With this script you will create a user named Tom, with password "123456" that belongs to administrator´s group. Log in with Tom and now you will be able to edit admin user and change his password. This way you will not delete all the other users you had defined previously.

Option 2

1. If you're admin, then open a terminal. To set the admin password on Linux, you can run: ./gsicontrol.sh configure-admin and on Windows: gsicontrol.sh configure-admin

2. If your admin account is working fine, then make sure you've enabled the Administration pages. You can do this by opening etc/main.cfg in a text editor and changing the line that says: status   disabled to status   enabled

3. Go to your Greenstone home page, click on the Administration Page button and, in the page that then loads, click on the List Users link to the left.

4. Login with the admin account. Then select the user whose password you want to reset by pressing the Edit button and filling in the new details.

Option 3

Delete the file greenstone/etc/users.gdb. Then go to admin page and log in with user admin. The password now defaults to "admin". Once logged in you can change your password. With this method you get access to the system but you are deleting all the other users you had defined.