Node:Installing tools, Next:Upgrading, Previous:Installing the daemon, Up:Installation

Installing the user tools

When you install the GNATS utilities, the user tools send-pr, query-pr and edit-pr are installed on the server machine. If your machine is part of a network, however, you may wish to install the user tools on each machine in the network so that responsible parties on those machines can submit new Problem Reports, query the database, and edit existing PRs. In the following discussion, machines with the GNATS user tools installed are referred to as client machines. In general, there are three distinct types of client that a GNATS server may have to cater for:

• Machines that are on the same local network as the GNATS server, i.e. machines that are under the same administrative control.
• Machines on the general, open Internet.
• Machines behind firewalls etc. which deny direct access over the network to the GNATS server.

Each type of client requires a different approach when it comes to providing access.

User tools on a local network

If all the machines involved reside on the same local network as the GNATS server, you can simply share out the directories on the server that contain the user tools, by default /usr/local/bin and the directory which contains the send-pr.conf configuration file (see The send-pr.conf configuration file), by default /usr/local/etc/gnats. If you have a heterogeneous environment, i.e. hosts running different operating systems, you need to create several shared GNATS installations, one for each platform. The send-pr.conf file is platform-independent, though.

In order to submit a new PR, send-pr would then be invoked as follows on the client machines:

send-pr -d hostname:port:database:username:password

Or by first setting the environment variable GNATSDB as follows (the exact syntax will vary depending on what shell you use):

export GNATSDB=hostname:port:database:username:password

Then, send-pr can simply be invoked without any options.

The other tools, query-pr and edit-pr, work in similar ways, honoring the -d option as well as the GNATSDB environment variable. See GNATS user tools.

User tools for remote users

When client machines reside on the general Internet, both security and practical considerations may make it impossible to provide a shared installation of the GNATS tools. In this case, you may choose to only provide access through a web interface such as Gnatsweb. For clients that need the GNATS tools, the following needs to be carried out on the remote machines:

1. Configure and build GNATS on the client machine
2. Configure send-pr on the client machine

You should unpack the distribution and run configure on the client machine in the same way as described in Configuring and compiling the software. Note, however, that you do not need to create a gnats user on the client and you should not use the make all info command to build. Instead, issue the following commands from the top level directory of the source distribution:

cd gnats
make install-tools
cd ../send-pr
make all install

This builds and installs the send-pr, query-pr and edit-pr tools on the client machine. You should now configure send-pr by editing the send-pr.conf file (see The send-pr.conf configuration file.)

Users on the client machine can now either use the send-pr syntax or the GNATSDBenvironment variable described in the previous section.

For sites that need to submit Problem Reports by having send-pr send e-mail instead of speaking directly over the network to the GNATS server, you need to create a problem report template on the GNATS server and have that template copied to a suitable location on the client machine (any filename and any location will do, as long as send-pr on the client machine can read the file). On the GNATS server, use the command

send-pr -p > filename

The file filename now contains a PR template for your database. Copy this file to the client. Then edit the send-pr.conf file that you created on the client, set the TEMPLATE variable to point to the template file (see The send-pr.conf configuration file) and make sure that the MAILPROG and MAILADDR varables in send-pr.conf are correctly set. You should now have a working remote tool installation.

For clients that have no direct network access to your GNATS server, such as those that are located behind strict firewalls, you either need to set up a web interface such as Gnatsweb (provided that the firewall lets web traffic through) or use the procedure above which sets up send-pr to submit Problem Reports by e-mail. In order to query PRs, users on the remote machines will then have to use the the e-mail functionality of query-pr (see Invoking query-pr. Editing PRs by e-mail is not possible, so clients in this group who need edit access have to get access through a web interface if possible.

Note that when send-pr is set up to work over e-mail, the GNATSDB environment variable and the -d command line option have no effect since send-pr is tied to a specific database by way of the value of MAILADDR in the send-pr.conf file.