Installing Beans

If you have not already done so, you should read the README file to obtain a general introduction and overview of Beans.

If possible, read the INSTALL.html version of this document.

Installing PostgreSQL

If you have not already done so, follow the Postgresql's documentation to install and set up Postgresql. This includes running PostgreSQL's initdb script to create and initialize the PostgreSQL server's default database.

When done, you should have PostgreSQL running. You should also have PostgreSQL's Java bindings installed (the jdbc7.1-1.2.jar) file. The JAR file must be installed in PostgreSQL's datadir, or /usr/local/share, or /usr/share, in order for Beans' configuration script to find it.

Reconfigure PostgreSQL

PostgreSQL's default configuration must be changed. The default PostgreSQL configuration accepts database connections through the local server's filesystem connections only. The Java bindings can only handle network logins.

1. Change to the postgres userid:
   
   su postgres
   
   
2. Run psql
   
   psql
   
   
   
   
3. Set a password for the postgres user. The default PostgreSQL configuration does not use passwords for logging in, instead using the database client process's userid for automatic authentication. This is not going to work for network logins, so passwords must be set.
   
   alter user postgres with password 'PASSWORD';
   
   
4. Get out of psql, and edit the the postgresql.conf file in the PostgreSQL's data directory. In that file, set the 'tcpip_socket' setting to 'true'. Optionally, set virtual_host in order for PostgreSQL to accept connections only on a single network interface. Setting virtual_host to 127.0.0.1 will accept network logins from local server processes only, instead of the default setting of accepting network logins from anywhere.

5. Edit the pg_hba.conf file to reconfigure PostgreSQL to use passwords for authentication. Remove the existing entry for local userid-based authentication, and use any one of the examples to set up 'crypt-based' authentications. For examples:
   
   local all crypt
host all 0.0.0.0 0.0.0.0 crypt
   
   This will use crypt authentication for all connections. Strictly speaking, local connections may remain the way they are, but it's better to have a consistent authentication mechanism for all logins. Also, it is possible to restrict connections to certain IP address ranges or only to certain databases. See the comments in pg_hba.conf file for more information.
   

6. Stop and restart PostgreSQL. Verify, using pgsql, that you can log in as the postgres user.

Install the Java runtime environment or the Java SDK.

Beans is distributed in two alternate packages:

• beans-VERSION.tar.gz - the source distribution
• beans-bin-VERSION.tar.gz - precompiled Java binaries

The source distribution contains the Java source code, and requires the Java software development kit. The bin package contains precompiled Java binaries, and requires only the Java Runtime Environment distribution. Both packages are the same; they are installed and configured exactly the same. Some *nix systems come with the Java Runtime Environment preinstalled. The bin package will be required unless JRE is upgraded to the full SDK.

NOTE: Beans requires Java 1.5. Older Java versions will not work.

Compile and install Beans

Beans uses the common GNU toolchain scripts to configure, compile, and install:

JAVABIN=pathname export JAVABIN ./configure [options]
make
make install

pathname should be the directory where Sun's Java 1.5 SDK binaries are installed.

This will install the following files and scripts:

/usr/local/bin/beansadmin - a script to start the administration tool

/usr/local/bin/beans - a script to start the application

/usr/local/bin/beansnetserverd - a script to start the RMI server

/usr/local/share/beans - JAR files, and other miscellanea, to be described later.

The usual configure script options may be used to specify different installation directories.

Create a Beans database

Run the beansadmin script to begin the configuration process. The first prompt is to log in to the PostgreSQL server as the database administrator. The default administrator server login is postgres, and the default login database is template1. Enter the postgresql userid's server password (set previously by ALTER USER) to proceed.

beansadmin is not designed to win any user interface awards. It's a small, rough application that is used occasionally for some maintenance tasks. The first order of business is to select "Create a new Beans database" button. This task runs CREATE DATABASE to create a new server database, and creates an empty administrative table in the new database.

Anyone who uses PostgreSQL must have a PostgreSQL login id and password. The next beansadmin task, "Create a new PostgreSQL user" adds prompts for a login id and a password, and creates. All this option does is run the CREATE USER command, which can be done manually in psql. This option is provided for completeness' sake.

A PostgreSQL login id must be registered before the Beans application can use it. The registration process adds the login id to the beans administrative table in the database. In beansadmin choose "Open a Beans Database", and enter the name of the database created earlier. Choose "Register a Beans user" then enter the PostgreSQL login id, and specify whether the login id should be read-only, read/write, or read/write/create.

The login id and its access level will be added to the beans administrative table. Note that this access setting is used by the Beans application only. Any PostgreSQL login id that has access to the Beans database can at least connect to the database. However, database tables are created without public access permissions, however anyone using the PostgreSQL login id can log in via other means, such as psql, and modify tables created by this login id even if it's access is set as read-only.

The read-only access setting limits the Beans application to only viewing, but not modifying, the existing files. The read/write access setting permits changes to existing files. The read/write/create access setting also allows the login ID to create new files.

Running Beans

Start beans using the following commands:

beans servername databasename

"servername" specifies the machine name of the PostgreSQL server, the default is localhost. "databasename" specifies the name of the Beans database to open. Enter the login id and the password on the first screen. From the "File" menu choose "New" to create a new file, with a default set of accounts. See the beans manual page for more information on using the application.

Running Beans via RMI

The machine that runs Beans must have the PostgreSQL Java bindings installed. It is possible to run Beans on a machine with just the standard Java Runtime Environment. Beans will connect to a server process running on a machine with PostgreSQL Java bindings, and use remote procedure calls to access the PostgreSQL database.

The beansnetserverd process must be started on the server to accept connections from Beans clients. See the beansnetserverd manual page for more information. Start beans as follows to connect to a remote server:

beans RMI name servername serverport myserver

"name" is the label of the beansnetserverd process on the server "servername", port "serverport". "name" does not necessarily have to be the name of the PostgreSQL database. "myserver" is optional. On a multi-homed client machine "myserver" specifies the IP address to use for connecting to the remote process. The PostgreSQL server name and Beans database is specified when starting beansnetserverd. beansnetserverd creates a Java RMI registry on the specified port, and registers itself using label "name". beansnetserverd can also register itself with another RMI registry (either the basic Java rmiregistry process, or another beansnetserverd), by using a different label. The same machine can be running multiple beansnetserverd processes on different ports, or the same port but different labels.

It is also possible to specify the remote RMI registry using the URL syntax:

beans RMI //servername:serverport/name

Note that this may not work reliably in all situations. Java's RMI registry classes, at least as of Java 1.4, do not work reliably on multihomed clients or servers. Java's RMI registry package selects an arbitrary IP address on multihomed machines to establish client and server connections. Unless all multihomed addresses are fully routable, the RMI registry may select an IP address that's not routable to its peer. The "myserver" argument to beans instantiates a custom RMI registry package that forces a selected local IP address.

Running Beans as a browser applet

Beans may be run as a browser applet. The browser must use a Java Runtime Environment plugin 1.5 or higher. Older browsers usually have an older Java Runtime Environment plugin, and must be upgraded. The Beans applet uses RMI calls to connect to the web server.

To use Beans as a browser applet, install the netclientapp.html and netclientapp.jar files on a web server. The web server must have Java installed with PostgreSQL bindings. The beansnetserverd process must also be installed on the web server. Edit netclientapp.html and specify the server address as follows:

<param name="port" value="serverport" />
<param name="rmiobject" value="name" />

or

<param name="rmiobject" value=":serverport/name" />

Browser applets always connect to the originating web server's address. It is not necessary to specify servername.

The web server must also be configured to return the correct MIME type for the .jar file. Use the following configuration setting for the Apache server:

AddType application/x-java-applet;version=1.5 .jar

Using SSL-encrypted RMI connections

Beans can encrypt RMI connections with SSL. This applies to the standalone application, and the browser applet version. In either case, see the beansnetserverd manual page for instructions on SSL-ifying the beansnetserverd server process (this mostly involves creating an X.509 certificate keypair, installing it, and providing a few extra arguments to beansnetserverd).

Beans RMI client

Two extra arguments to the beans command - the literal "SSL", and a pathname to a file with the server's public X.509 key - enables SSL for RMI connections from the beans client. These arguments may be saved in $HOME/.beans, conveniently.

Beans browser applet

Copy the server's public X.509 key to the web directory with the netclientapp.jar file, and name it certificate.txt, and include an additional applet parameter:

<param name="protocol" value="SSL" />