Installation instructions Installation instructions Last modified: 1 January 2002
These are instructions for installing LEDA from scratch on a machine running Linux 7.x. Upgrading instructions for those with older installations are in a separate document. General information about what LEDA is and the purposes to which it can be put are elsewhere.
Major steps in installing LEDA v0.1 (if you're upgrading from an earlier version, see the upgrade instructions):
The time needed to install LEDA will vary greatly with your experience, equipment, and expertise, and how many times the phone rings while you're trying to do it. We suspect it would be hard to do in less than half a day. Most people will need a full day to install it, much of which will be spent waiting for CDs and disks to spin.
If you just want to get a feel for what Leda does and how it works, it's not necessary to do an installation. We run a public server that permits you to test-drive LEDA through a variety of situations. You can see what the submission process is like, how well the conversions work, and so on. Because we're interested in knowing who is kicking LEDA's tires, we keep the demo site behind a password -- you'll need to ask us for it.
If you already have a box running Linux and some of the LEDA underpinnings (say, mySQL or Apache with PHP and mod_perl support), it will be tempting to add more stuff to your existing box to see if you can get LEDA to work. You can probably make this work if you know what you're doing, but it will not be super-easy. Most people will be happiest installing LEDA on a shiny, new, clean box. Honest. We've spent a fair amount of time with both approaches and it's a lot easier to build from scratch. If you're trying out the software and you don't have the resources to put it on its own machine, we're happy to help you make it work. But if you have any choice in the matter, and you're tempted to layer LEDA atop an existing setup because you think it will save time or effort, you're probably mistaken. Building from the ground up is much easier.
If you remain determined to ignore all this good advice ;-) and install "just a few RPMs" to get LEDA going.... beware. We've fallen in this hole ourselves. The RPMs for the various LEDA underpinnings (mySQL, Apache, PHP, mod_perl) all embed assumptions about file layouts and (especially) configuration that may or may not be the same as ours, or as those of other RPMs. Occasionally these are compiled in and have to be overridden by using an external command line parameter or configuration file entry. If you're trying to fit in the last piece of a software jigsaw puzzle, it is usually easier to build from source, where you can control the installation a little more closely. Where possible we've made LEDA so that you can reconfigure it to fit with an existing setup (see in particular our explanation of LEDA's configuration file), but it is still a picky and annoying business.
LEDA runs on pretty much anything that will run Linux with XWindow support.
System administration
We tried to keep these instructions oriented toward relative Linux novices. They go deeply enough into things like basic security practices to keep you from getting into serious trouble. Some things, though, you'll have to take care of on your own. Important ones include security (you can always do more with security), and keeping things backed up. At the LII we use and like the Amanda backup software; others integrate Linux boxes into their regular server backups via Samba. You'll also want to look into update logging and other methods of maintaining up-to-the-minute backups of the mySQL databases. Bottom line: you'll need to administer the system just as you would any other, and while we've tried to give you the tools to get started, this isn't a manual on system administration.
Access policy: wide-open out of the box
Out of the box, LEDA does not enforce any access policies. Anyone can submit documents, approve them for publication, or act as an administrator. It's not that way because we don't believe in access restrictions -- it's that way because we can't anticipate the individual needs and policies of everyone who might put up a LEDA server. Two levels of access restriction are available -- through the Web server via Apache configuration, and through the database via the mySQL grant tables. We describe some possibilities and techniques in our document on enforcing access policy.
You'll need to gather some information before you install your LEDA box. Almost all of this is information you'd need to install any Linux box on a network: hostname, IP address, netmask, gateway, and DNS server. You may also need to know some details of your hardware; the RedHat installation documents are good at telling you what you'll need. Finally, you'll need to make some decisions about what you want to call your LEDA repository and how you want to name documents in it. Most of the information you'll need relates either to the name of your organization or the name of your repository or is some variation on it, and isn't very challenging to come up with. The one thing you'll probably need to think through carefully is what you will use as your naming authority for documents. LEDA document identifiers use the CNRI handle scheme, which requires that anyone making up handles use a unique naming authority string as a way of guaranteeing the uniqueness of identifiers. Many University library systems already are using the handle scheme or some variant of it, and yours may have something to say about what naming authority you should use.
If you're not familiar with Linux security practices, we suggest taking a look at the Linux Security How-To before you even begin installation. Specific security tips are listed in a later section.
Follow the instructions for installing RH7.1 from the distribution CD-ROMs. Early on, you'll be offered a choice of what class of system to install. There are many ways to approach this, but probably the most efficient is to choose "server system" . This will minimize the number of additional packages you have to select manually from the installation menu. A little while later -- after you've fed the machine some configuration information -- you'll be presented with a dialog box labelled "Package Group Selection". Choose "X Window System" and "Web server", and check the "Select individual packages" box -- you will have to add some packages by hand.
Note that different releases of Linux 7.1 (Standard, Deluxe, and Professional) have slight variations on package names and default package choices. We have noted such differences here where possible. Beyond the default "web server" bundle, from the individual package list, we chose (in case we missed any, a complete package list for our test system is available for reference):
We strongly recommend you install all of these. Not all are strictly necessary at the moment, but some are great conveniences and others are things we anticipate a use for in future releases of LEDA. . The install process will ask you to ok some dependencies (given the option, choose "install packages to satisfy dependencies" and let them be installed along with everything else).
When the install asks you if you want to automatically start XWindow on boot say "no."
After installing RedHat and admiring your handiwork, install all the updates and errata relevant to your machine. You will need to be root to do this, and all subsequent steps.
/usr/sbin/rhn_registerRedHat 7.1 is by default quite tightly secured. Most services are off and need to be enabled in order for you to do anything other than work from the console. At a minimum, you'll need to see to it that the Apache web server and mySQL database server start up; you may also need to turn off some firewall rules (if you opted to install the kernel-level firewall) and establish some form of remote access to the machine. Much of what you do in this part of the installation will employ the very handy chkconfig utility; a look at its man page (say man chkconfig) beforehand might be a good idea.
At this point, you need to acquire the LEDA distribution (you won't be doing much with it yet, but it contains some installation scripts and aids that come in handy in the next few steps). Installation is quite simple:
As installed, the mySQL installation is wide open. You should set a root password immediately by saying:
mysqladmin -u root password new_password
where new_password is whatever you want for your mySQL root password. There are other methods of doing this; if you run into trouble, see the detailed explanation in the mySQL user documentation at www.mysql.com/documentation/mysql/bychapter/manual_MySQL_Database_Administration.html#Default_privileges (section 4.3.4 "Setting up the Initial MySQL Privileges"). LEDA-specific databases and users will be installed later.
phpMyAdmin is a free database administration utility designed to work with mySQL. It's very handy to have. To install it:
Now, you need to set it up to use mySQL's builtin access control. To do this, you need to create a "read-only" user that can look at the mySQL permissions database. Then you need to tell phpMyAdmin to use that user for its "advanced authentication" scheme.
mysql
-u root -pgrant select on mysql.* to rouser@localhost
identified by 'password'; (note that the quotes are required)
flush privileges;
quit;
where password is any password of your choosing (and
rouser is a new read-only user who can see the mySQL permissions tables).
cd /var/www/html/phpMyAdmin$cfgServers[1]['adv_auth'] = false; // Use
advanced authentication?
$cfgServers[1]['stduser'] = 'root'; // MySQL standard user
$cfgServers[1]['stdpass'] = '';Now try invoking phpMyAdmin from a browser by aiming it at http://leda.law.somewhere.edu/phpMyAdmin. You should get an authentication dialog; you should then be able to access phpMyAdmin as 'root' using the mySQL root password, or as any other mySQL user you may have created.
Next, read over: man xinetd and man chkconfig
Turn off unnecessary services and daemons
run:
/sbin/chkconfig --list | more
You will see a table listing first services and daemons and their run-level state (on/off), and then xinetd based services listed as on or off, independent of run-level.Comb carefully through each service and daemon that chkconfig shows you and turn off everything that you either do not need, or that you are not sure of it's purpose. Popular useless daemons are finger and talk. Some of the more dangerous ones are rsh (remote shell) and rlogin.
An example command to turn off rsh is:
/sbin/chkconfig rsh off
An example command to turn off lpd at run levels 0, and 2-5 is:
/sbin/chkconfig --level 02345 lpd off
To see how chkconfig is actually changing the config files (useful to know) look at the files in /etc/xinetd.d/ while you make these changes. When you disable an xinetd service a line goes into the config file as such: disable = yes You could also do this by hand. You could also just move or delete the configuration files.
If you would like to keep a daemon or service running you can restrict the host IP addresses that can access it by editing the configuration file to add a line that says:
Finally some installs may still include some inetd/inetd.conf functionality so check these as well.
Good candidates for this treatment are finger, talk, and ntalk. You may want to remove others, or limit access to them.
Startup scripts for a variety of system daemons are found in the /etc/rc.whatever directories. Remove the startup scripts for any services you can do without, eg. lpd.
Obviously, we can't offer a full guide to Linux security here. Others do; we like the following as starting points:
Leda depends on a number of Perl modules available through CPAN. You will want to install these using CPAN from the command line:
Important note: installing some CPAN modules will cause an updated version of perl to be installed. If this happens, don't go any further until you've read the instructions on dealing with out-of-sync perl versions. This is a place where an ounce of prevention is worth a lot...
Here's a list of the modules that need to be installed:
You can test to see if all perl modules were correctly installed by saying
perl /usr/local/leda/install-help/perl_test.pl
The test routine will complain if it can't find any of the modules that Leda needs. The quickest solution to this problem is usually to find out where CPAN actually installed the modules in question and add appropriate 'use lib' statements to perl_test.pl and perl_preload.pl.
rtf2latex2e is used in the process that converts RTF files to printer-friendly PDF (Acrobat) files. To install it:
LEDA uses the transfig and libwmf graphics libraries as part of a conversion package to convert charts, illustrations, and equations from the WMF format embedded in RTF files to Web graphics. To install it:
NB: libwmf is changing rapidly, and for the better. It may be worth checking the project homepage at http://www.wvware.com/libwmf.html for a newer version, as we anticipate that these will help significantly with some graphics-conversion problems in Leda.
cd /usr/local/leda/install-help/mysqlsh mysql-setup.shYou'll be asked for the mySQL root password you set up a few minutes ago. mysql-setup.sh should give you output showing that user 'anonymous' now has access to all of Leda's tables and so on. This method is pretty simplistic. Much more complicated setups are possible, depending on your needs and level of paranoia. (Actually, the output from this shell script is pretty obscure. You can more easily check your work with phpMyAdmin)
At this point, you need to set up Apache to make good use of mod_perl, and to enable access to the various LEDA CGI scripts. The first step is to put a script in place that will cause Apache to preload some perl scripts (this greatly enhances performance).
PerlRequire /usr/local/leda/install-help/apache/perl_preload.pl
ScriptAlias /leda-cgi/ "/usr/local/leda/cgi/"
<Directory /usr/local/leda/>
Header set Pragma no-cache
Header set Cache-Control no-cache
</Directory>
<Directory /usr/local/leda/cgi>
Options ExecCGI
PerlHandler Apache::Registry
PerlSendHeader Off
</Directory>
In addition, you may want to add some directives that will control access to
various parts of LEDA. See our document on access control
for suggestions about policy and implementation.
ledacfg.xml contains all of the configuration information that is unique to your LEDA setup. Editing it is a straightforward process, though we cheerfully confess that some of the terminology involved is a little obscure. The version we ship contains information for our development setup, which should at the least be illustrative. We provide a guide to the configuration file that will help you figure out what's what. At a minimum you will need to change some of the mySQL configuration information to conform to your system. At the least, you need to know where RedHat is keeping the mySQL socket -- by default, RedHat puts it at /var/lib/mysql/mysql.sock . You may need other information depending on how you configured mySQL, etc.
html-trn determines the appearance of your converted HTML documents (it is a configuration file for rtf2html). As shipped, it includes local information that won't be right for your site (such as logos, links to home pages, etc.). Eventually we will build an apparatus to configure it from the contents of ledacfg.xml, but for now you'll have to go through it by hand. Documentation on the html-trn format (and what you can do with it) is here. FYI, it is also possible to exercise control over the conversion of special characters and other problematic things; see the documentation in /usr/local/leda/bin/r2h/.
If you've got a server up, we want to know. Get in touch with us at leda-team@leda.law.cornell.edu. We also run a listserv for LEDA users and advisers; send the one-line message SUBSCRIBE LEDA-L to listserv@listserv.law.cornell.edu to sign up. At the moment there is only one list for all LEDA participants, no matter their interests, but we will subdivide the list into interest groups as the number of participants grows.
Many people will want to "preload" information for regular contributors to their Leda site (authors). For example, a law school might want to preload information on its entire faculty roster. The utility /usr/local/leda/utils/loadcreators.pl accomplishes this, given a file in the same format as Facultynames.txt (in the /usr/local/leda/util directory).