Installing BATTS

	Installing BATTS consists of five steps: installing BATTS'
	prerequisites; modifying and installing the configuration
	files; creating the database; installing the scripts;
	and installing the mail gateway.  If you are familiar with
	Unix or Linux systems, BATTS should be relatively easy to
	install. These instructions were written based on installation
	of BATTS on a Red Hat 7.1 system, though other Unix systems
	should be rather similar. BATTS has never been installed on
	a Windows system. I doubt that it would run out-of-the-box
	on any Windows system, but if you manage to get it working,
	please let us know.


Installing Prerequisites

	In order to function, BATTS needs several other pieces of
	software installed. These include Perl, MySQL, Sendmail
	or equivalent, and several Perl Modules. Installation
	of Perl and MySQL are not trivial; both ship with many
	modern Linux distributions and, in these cases, the default
	installation should suffice.  If you are running a Unix system
	without Perl installed (egads!), Perl may be obtained from
	www.perl.com1. BATTS was developed on a system running Perl
	5.6.0; Any version of Perl greater than 5 should probably work,
	but nothing else has been tested.  If you are successfully
	running BATTS on a system with a different version of Perl,
	or if you have found a version of Perl incompatible with
	BATTS, please send me mail at <jon@cluestickconsulting.com>
	so that future releases of this manual can be kept up-to-date.
	MySQL is available from www.mysql.com2. Red Hat 7.1 includes
	version 3.23.36; this is the version of MySQL that BATTS
	has been developed and tested with. Any version greater than
	3.23.0 should work; if you are successfully running BATTS with
	a different version of MySQL, or you have discovered that
	BATTS is incompatible with a particular version of MySQL,
	please send e-mail and let me know.  Virtually every Unix
	and Linux distribution comes with either genuine Sendmail or
	a substitute that contains a binary named (or symbolically
	linked to) sendmail. As long as it accepts standard Sendmail
	options, we don't really care if it's the real thing.  3 If
	you are using something other than stock Sendmail and needed
	to make changes in order to make it work, please send me
	mail. (Are you noticing a pattern here?)


Installing Perl Modules

	In order to work, BATTS needs the Perl DBI (Database Interface)
	module and the DBD (Database Driver) module for MySQL
	installed. In addition, the Mail::Header and Mail::Internet
	modules from the MailTools package are required.  The DBI home
	page is located at http://dbi.symbolstone.org/4. Complete
	instruc- tions for installing DBI and DBD may be found
	there. Red Hat Linux and some other Linux distributions include
	packages of the DBI and DBD modules. Red Hat's pack- ages are
	named perl-DBI and perl-DBD-MySQL; they are available as part
	of the base Red Hat distribution for versions 7.0 and later.
	If these modules are not already installed on your system,
	they can be installed via CPAN, the Comprehensive Perl Archive
	Network. You can enter the CPAN shell by running the command
	perl -MCPAN -e shell \; as root. You will be asked a number of
	questions regarding the installation of CPAN. Answer these as
	best you can.  Eventually you will arrive at the CPAN shell
	prompt, which is simply a line that begins with the word
	cpan> followed by the cursor. DBI and DBD are available as
	bundles, which are essentially a group of separate modules. To
	install the DBD bundle, type install Bundle::DBD at the CPAN
	prompt and hit Enter. The DBI may be installed in the same
	fashion; not surprisingly, it is named Bundle::DBI.  After
	installing these modules, you can install the Mail::Header
	and Mail::Internet modules in the same fashion. There does
	not appear to be a MailTools bundle, though it should not be
	difficult to install the entire MailTools package via CPAN.
	If all of these commands worked, you have installed all of
	the prerequisites for BATTS.  Congratulations!


The BATTS Security Model

	BATTS doesn't have any security. Well, almost.	BATTS will
	create for itself a MySQL user named batts who has full control
	over the ticketing system. Anyone who can run the BATTS binary
	and who can read the batts.myrc file discussed below will be
	able to do anything to the BATTS ticketing system, including
	the ability to delete records or even the entire database.
	BATTS assumes that you will use the Unix permissions to control
	access to the batts.myrc file, which contains the database
	connection information. Our advice is to create a group named
	batts in your /etc/group file and to make all authorized users
	of the ticketing system members of that group. Other people
	will be able to create tickets and even add information to the
	ticket log via the e-mail interface.  Once you have done this,
	all you need to do is to change the group of the batts.myrc to
	batts and change permissions on the file to 0640. After this,
	only members of the group batts and the owner of the file,
	who is probably root, will have the password to the database.
	One last note: Unix group information is obtained at login;
	once you have created the group, log out and log back in to
	become a member of that group. Until you log out and back in,
	you will not be a member of the batts group.


Modifying and Installing Configuration Files

	BATTS has three configuration files that need to be installed
	in /etc: batts.myrc, battsrc, and batts-reply.txt. Sample
	files are included in the config_files sub- directory of the
	BATTS distribution; each of these files must be modified before
	you can use BATTS.  The batts.myrc file contains the database
	connection information. It includes the host name, database
	user, and password for the BATTS database. You will need to
	change the host= and pass= lines of the configuration file, at
	a minimum. We recom- mend sticking with batts as the user name,
	but you can change this as well if you desire.	The battsrc
	file contains configuration information required by the BATTS
	program for sending mail. This file is read directly by Perl,
	and is in fact live Perl code. If you don't have any complex
	configuration, this file is quite simple. These are variable
	assignments, which are of the general form

	$variable = 'value';

	All Perl variable names (the ones we care about, anyway) begin
	with a dollar sign.  The only two configuration variables
	supported at present are $return_address and $sendmail. You
	should not need to alter the assignment statements
	except for the values indicated between single quotes.
	The $return_address variable should be set to the return
	address for the ticket- by-mail system. If you choose not to
	use the ticket-by-mail system, then set this to something that
	will be seen by a live person, as it will also be used as the
	return address when mailing customers the resolutions to their
	problems.  The $sendmail provides the full path to the sendmail
	executable and its required command-line options. At a minimum,
	the -oi and -t options are required; the - odq option queues
	the message in the local sendmail queue. If the host on which
	you run BATTS does not automatically send queued mail, remove
	this option. Many systems do not have the sendmail binary
	in /usr/sbin/sendmail as is standard on most Linux systems;
	other Unix flavors tend to use /usr/lib/sendmail instead. If
	the path is wrong, then sendmail will not be run and mail can
	not be sent.  The batts-reply.txt file includes the text of
	the message sent to users when a new ticket is generated. At
	the very least, change the e-mail address included in the
	mes- sage to point to your system.  Installing the files
	are easy. Simply copy them to your /etc directory, change
	the group to batts, and change the file mode to 0640. This
	can be done with the following sequence of commands executed
	from the config_files subdirectory of the BATTS distribution:

		cp batts.myrc battsrc batts-reply.txt /etc
		pushd /etc
		chgrp batts batts.myrc battsrc batts-reply.txt
		chmod 0640 batts.myrc battsrc batts-reply.txt
		popd


Creating the Database

	In the sql_scripts, there are several files that you will need
	to modify. First, edit the create-tables.sql script to point
	to your account and password. The fourth line of the file,
	which begins grant ALL on batts.* is the line that needs to
	be modified.  If you have changed the database account name
	in the batts.myrc file, then change batts@localhost to point
	to the account name. It may be necessary to change lo- calhsot
	to the actual host name of your system as well. The password,
	which is set by default to gimmeanewpassword should also be
	changed to match the setting from your batts.myrc file.  Next,
	modify people.txt, and change the e-mail address to match that
	of your trou- ble ticketing system. The file is tab-delimeted,
	and the database is very sensitive to the format. The name
	unassigned must not be changed. The name of the trouble ticket
	system, which is set by default to BATTS Trouble Ticket System
	may be changed, but caution is warranted.  In the customers.txt
	file, change internal to a short username to identify the
	orga- nization running the ticketing system, and (following a
	tab), change Your Company Name Here to a reasonable long name
	for your company or organization.  Finally, you can run the
	initialize-database script to create the database. If you have
	set a password on MySQL's root account, run with the -p option.


Installing the Scripts

	There are two scripts that are part of BATTS: batts and
	ticket-via-email. The first line of each of the scripts must
	point to your Perl installation: if your preferred version of
	Perl is in /usr/local/bin, change the part of the first line
	that reads /usr/bin/perl to read /usr/local/bin/perl instead.
	The scripts merely need to be copied to a binary directory
	on your system; we rec- ommend that they be installed in
	/usr/local/bin. They may be installed via the following
	sequence of commands executed from the bin subdirectory of
	the BATTS distribution:

		cp batts ticket-via-email /usr/local/bin
		pushd /usr/local/bin
		chgrp batts batts ticket-via-email
		chmod 0750 batts ticket-via-email

	At this point, you may wish to install symbolic links for the
	various BATTS com- mands. If you are using a Bourne shell
	derivative such as the Korn Shell or BASH, you may execute
	the following command from the /usr/local/bin directory to in-
	stall symbolic links for most of the BATTS commands:

		for foo in `batts show-commands |
			egrep -v '(help|mysql|touch)'`
		do ln -s batts $foo; done

	If you have a command on your system named log, you should
	add log to the egrep command, which eliminates commands from
	the list of installed symlinks. It is pre- sumed that you do
	not wish to override mysql or touch commands, and the help
	would be confusing for most users, who will not intend to be
	using BATTS.


Installing the Mail Gateway

	Installing the Mail gateway is not difficult, but requires
	some modest system ad- ministration experience. Because
	of the group-membership security requirement for BATTS,
	it's simplest to create a user who is a member of the batts
	group. On my system, I created a user named trouble; if this
	user will not by default receive mail sent to the return
	address you configured in the above configuration files,
	you should create an alias that points at this account.
	Most Sendmail installations have smrsh (Sendmail Restricted
	Shell) configured. This requires that programs which may be
	executed by users be stored (or symbolically linked to) in
	the smrsh directory. On my Linux system, this is /etc/smrsh,
	but this may differ on other Unix flavors. From that directory,
	create a symbolic link to the ticket-via-email script. On my
	system, this may be done as follows:

		pushd /etc/smrsh
		ln -s /usr/local/bin/ticket-via-email ticket-via-email
		popd

	The next step is making the script execute when mail is sent
	to the appropriate e-mail address. Assuming that you created a
	user account for BATTS, create a .forward in that user's home
	directory which points to the script. The script name should
	be in quotes, with a pipe (|) prior to the filename within the
	quotes. On my system, trouble's .forward file reads as follows:

		"|/etc/smrsh/ticket-via-email",root

	The ,root at the end of the line is optional. It mails a copy
	of the incoming ticket to everyone who is listed in the root
	alias. If instead you wanted the ticket to be pro- cessed by
	the script, mailed to everyone on the <developers@example.net>
	mailing list run on another machine, and to a user named joe
	on the local machine, this line could read

	       "|/etc/smrsh/ticket-via-email",developers@example.net,joe

	The file should be writable only by the user; mode 0644 is
	fine. If other users can write to the .forward file, then
	Sendmail will refuse to execute it.  While it may be possible
	to use an alias in /etc/aliases and have the ticket-via- email
	script setgid to the BATTS group, my gut feeling is that this
	would be less secure than creating another user. I have no real
	evidence for that assertion, however.  At this point, BATTS
	is installed on your system. Send a test ticket in via the
	e-mail gateway and see that everything performs as expected.
