Hacking J-Bird: Remote access to your J-Bird database

Although J-Bird is distributed as an independent application that makes no use of a network, it is possible to make your J-Bird database accessible over a network. For example, you may have a wireless network at home, and you would like to access the J-Bird database on the computer in your study from the patio using your laptop (while you have a pair of binoculars at hand). Or, you have broadband network access at home (e.g., cable modem or DSL), and you really need to access J-Bird from work or school. This page describes how to set up J-Bird so that you can access your database remotely.

If you configure the J-Bird database to use a network, you are assuming a security risk. Briefly, the database will be listening on the network as a server. Anyone on the network who can reach your computer can try to connect to the database. Although the J-Bird database does have a username and password, you should always assume that they can be seen by anyone who sniffs the network. Use of public networks is not recommended. It is strongly recommended that you use a private network (e.g., a home network that is isolated from the internet by a firewall), use a virtual private network, or an ssh tunnel to connect to the database server. If you don't know what these things are or if you don't have time to set them up, do not configure the database to listen on the network.

By default the Mckoi database that powers J-Bird is unaware of the network. The database driver directly accesses libraries that are the database engine. To access the database remotely, you will configure the Mckoi database to run as a server, and you'll configure the remote computer as a client. Both computers will have the J-Bird software installed on them, but the database will exist only on the server.

Note that while you are running the database as a server, it is available only on the network. You cannot run J-Bird on that computer as a independent application. There are two ways of dealing with this. One is that you run the database as a server only when you want to access it remotely. Turn on the server, go to the remote place, access J-Bird, return to the server, and turn it off so you can run the J-Bird application locally. Alternatively, you can run the database engine as a server all the time, and configure both the copy of J-Bird at the remote locality and the copy that resides on the computer that is the server to be remote database clients. The decision that you make is reversible.

Setting up the server

J-Bird not yet installed

If you haven't already installed J-Bird, install it according to the directions. Before you build the master species list, change the default username and password that the database will have. To do so, copy the file J-Bird.prefs.mckoi to J-Bird.prefs. Then, edit the J-Bird.prefs file to change both the JDBCUser name and JDBCPassword setting to have values other than the defaults. Build the master species list, and skip to the section "Starting the server".

J-Bird already installed

If you have already built a master species list with the default user name and password, it is strongly recommended that you change the password. To do so, you'll run an Mckoi query tool, and enter a query that changes the password. Run the query tool from the J-Bird directory with the command

	java -cp downloads/drivers/Mckoi/mckoidb.jar:downloads/drivers/Mckoi/gnu-regexp.jar com.mckoi.tools.JDBCQueryTool -url jdbc:mckoi:local://./mckoidb.conf -u jbird -p chirp

	java -cp downloads\drivers\Mckoi\mckoidb.jar;downloads\drivers\Mckoi\gnu-regexp.jar com.mckoi.tools.JDBCQueryTool -url jdbc:mckoi:local://./mckoidb.conf -u jbird -p chirp

	ALTER USER 'jbird' SET PASSWORD 'new_password'

Starting the server

To start the database server, go to the J-Bird directory and run the following command

	java -jar downloads/drivers/Mckoi/mckoidb.jar  -conf mckoidb.conf

	java -jar downloads\drivers\Mckoi\mckoidb.jar  -conf mckoidb.conf

Configuring J-Bird to be a remote client

On the remote computer, install J-Bird, but do not build a master species list.

Create two files in the J-Bird directory. They can be empty, but they need to be there. The files are: UPGRADE_NO_DUMP and UPGRADE_NO_POST_PROCESS. The file UPGRADE_NO_DUMP prevents the installer from backing up the database at the beginning of future upgrades. The file UPGRADE_NO_POST_PROCESS prevents the installer from trying to modify the database after future upgrades.

Copy the J-Bird.prefs file from the J-Bird directory on the server to the J-Bird directory on the remote computer, and edit the JDBCURL entry. In the freshly copied preferences file, the entry will be

	JDBCURL = jdbc:mckoi:local://./mckoidb.conf

	JDBCURL = jdbc:mckoi://hostname/

	JDBCURL = jdbc:mckoi://192.168.96.21/

Running J-Bird as a client on the database server

While your are running a database server, you can no longer just run J-Bird on the server computer. To run J-Bird while the server is running, you need to configure the copy of J-Bird on the server to behave as a client, too. Save a copy of the J-Bird.prefs file as J-Bird.prefs-orig, and edit the J-Bird.prefs file, changing the JDBCURL line to appear as follows:

	JDBCURL = jdbc:mckoi://localhost/

. Again, do not concurrently run more than one copy of J-Bird against the database server. Although the server allows multiple connections, J-Bird itself has not been written to allow more than one connection.

Upgrading. If you are running J-Bird as a client on the server machine, you will be able to upgrade J-Bird as usual until the time comes that there is an upgrade of the Mckoi database engine that requires some code to be run to reformat the database files. (This was true for the upgrade from Mckoi 0.93 to Mckoi 0.94 that occurred between J-Bird versions 0.4.0 and 0.4.1.) If such a time comes again, you'll need to revert to the original configuration for the upgrade. Before upgrading in the future, always check the page http://j-bird.sourceforge.net/hack-mobile.html#upgrade to see if this is required. The original non-network configuration is needed for:

• upgrade to J-Bird 0.4.1 from any earlier version.

Shutting down the server

To cleanly shut down the database server run following the command on the server from the J-Bird directory

	java -jar downloads/drivers/Mckoi/mckoidb.jar -shutdown username password

on Linux or Mac OS X, where username is the name that you have set for the database and password is the password. For example, if the user name that you set is rover and the password is barkbark, the command is

 
	java -jar downloads/drivers/Mckoi/mckoidb.jar -shutdown rover barkbark

	java -jar downloads\drivers\Mckoi\mckoidb.jar -shutdown username password