CGIBurn::README - Instructions for using and installing CGIBurn, a Web-based CD burning package.
CGIBurn is a Web-based front end for burning CDs. Out of the box, it knows how to copy from one data CD to another, from a directory of files onto a CD, from a CD into a directory of files, and some other, less useful options (See SETUP below for the less useful options).
It is written in Perl for use under Unix. See REQUIREMENTS for more details about exactly what is required.
CGIBurn is written by Scott Gifford <sgifford@tir.com> Please report any questions, problems, complaints, or praise to me at that address.
The official CGIBurn Webpage is at
http://www.tir.com/~sgifford/cgiburn/
Writable CDs are incredibly useful for lots of things, including making backups, archiving large amounts of material, sharing large amounts of data, and duplicating music and data CDs.
The two big drawbacks are that they can't be used like a regular drive, so you can't use them as normal fileshares, and that they pretty much tie up your entire machine while you are burning, or else you run the risk of destroying your CD.
That's what CGIBurn is designed to solve. It provides an easy-to-use frontend to CD burning, which allows copying from one CD to another, or from a directory (which can be shared by normal filesharing). And it is designed to run on a separate, dedicated machine, so that you can keep on using your main machine to do whatever you want to do, no matter how CPU intensive it is. And the dedicated machine doesn't have to be that fast, so you can use your old PC that's been sitting in your basement since you got that shiny new Pentium II/II/Athlon chip. :)
CGIBurn requires a computer which is fast enough to keep up with the burning process. I am currently using it on a Pentium 133 with no problems.
CGIBurn is a front-end to other CD burning and copying programs, such as cdrecord, mkisofs, and standard UNIX utilities awk, ps, and rm. As such, it requires that copies of these programs be available and working before you can even think about using it. The following programs and versions were used for testing this release:
cdrecord 1.9
mkisofs 1.13 (from the cdrecord 1.9 package)
rm GNU 4.0p (from fileutils)
eject 2.0.2
awk GNU 3.0.4
ps procps 2.0.6 (Linux version)
CGI Perl module 2.74
For the suid helper (which gives burning processes high priority)
Safe setuid scripts (or a working suidperl)
For copying between directories:
GNU tar (gtar) 1.13.17
rm, awk, ps, and eject should come with your system. CGIBurn uses options specific to GNU tar, and expects it to be available as ``gtar''.
cdrecord can be downloaded from:
http://www.fokus.gmd.de/research/cc/glone/employees/joerg.schilling/private/cdrecord.html
The CGI module can be installed by typing
perl -MCPAN -e 'CPAN::Shell->install(CGI)'
at the shell, with any recent version of Perl.
Additionally, CGIBurn requires some version of Perl 5.0 or newer (tested with 5.005_03) on some version of Unix that supports the programs (tested on Linux kernel 2.2.14, on a RedHat 6.2 system).
For job control to work, your version of ps must support the -o
option, which asks it to print user-specified information about the
processes.
Other than that, though, it shouldn't be too sensitive to kernels or distributions, as long as the Perl works and the above programs work. It might not even require Unix, if you can find versions of cdrecord and mkisofs that support other operating systems.
CGIBurn is written as a series of CGI scripts that run backend libraries and driver programs. In order to run the CGI scripts, you'll need a Web server that supports CGI scripts written in Perl. This distribution was tested with Apache 1.3.12.
Note that by default, a helper script is installed setuid to root on the system. This script raises the priority of processes which write to the CDR, to make sure other processes don't overwhelm your computer, and cause your CDR buffer to dry up, your burn to fail, and your CDR to be destroyed. If your system doesn't run setuid Perl scripts securely, you should not use the helper script. See CONFIG for information on disabling the helper script.
CGIBurn installs itself in various directories beneath your Webserver's root directory (which you tell it in your configuration file). It expects you to have a subdirectory called ``html'', and it makes a subdirectory there where it installs its static Web pages. It expects you to have a subdirectory called ``cgi-bin'', and it makes a subdirectory there where it installs its CGI scripts. It expects you to have a subdirectory called ``cgi-lib'', and makes a subdirectory there where it installs libraries and tools used by the CGI scripts. It expects you to have a subdirectory called ``cgi-data'', and makes a subdirectory there where it keeps miscellaneous data files. It expects you to have a subdirectory called tools, and makes a subdirectory there where it keeps tools intended for use by the administrator.
Note that ``cgi-data'', ``cgi-lib'', and ``tools'' do not come standard with most Web server setups; you will probably have to create them. If you would like CGIBurn to go ahead and make any necessary directories, run it with the '-m' option.
If you would like to install CGIBurn in different subdirectories of your Web server root, or in some completely different way, you can edit the configuration files to do that. See CONFIG for more information.
If you install CGIBurn as ``cgiburn'', it looks basically like this (directories marked with '(Writable)' are writable by the Webserver; directories marked with '(Not Created)' will not be created automatically --- they must be there already):
/path/to/server/root/
html/ (Not Created)
cgiburn/ - Static Web pages
images/ - Static images
doc/ - Documentation
jobs/ - Job information
(Writable)
cgi-bin/ (Not Created)
cgiburn/ - CGI scripts
cgi-lib/ (Not Created)
cgiburn/ - Libraries & tools
lib/ - Libraries
bin/ - Tools
cgi-data/ (Not Created)
cgiburn/ - Data files
conf/ - Configuration
doc/ - Documentation
lock/ - Device locks
(Writable)
templates/ - Page templates
tools/ (Not Created)
cgiburn/ - Admin tools
This is the default configuration because it normally won't require any changes to a Webserver's configuration (except making the ``cgi-lib'', ``cgi-data'', and ``tools'' directories), since it puts everything that the Webserver needs to know about in directories that it will usually already know about. Some people like to keep things all in one place, and change the configuration of their Web server to look in that place. They may want to write their own configuration files to customize the installation location. See CONFIG for more information.
All locations are completely configurable; see the Advanced Options section of CONFIG, and the various configuration files. Other configurations have only been lightly tested, however, so if you have any problems you may need to fix them (see HACKING), or drop me an email. If you have a layout you think is fantastic, please email it to me, and if I like it I'll include it as an alternate layout.
Here's a step-by-step overview of the normal process.
You should su to the user that your Web server runs as, and run a few test runs with cdrecord (possibly with the --dummy switch, to avoid wasting CDs) before considering this step completed.
cgi-data/conf/local.conf
See local.conf in CONFIG for more information on how to configure CGIBurn properly.
cgi-data/conf/devices.conf
See devices.conf in CONFIG for more information on how to configure devices properly for CGIBurn.
tools/smartinstall
That will copy all of the files into the correct locations, fix the Perl scripts to include the correct libraries, generate a configuration cache, and select a PS module for your system.
smartinstall may detect problems with your configuration or your system. If it does, you'll need to correct these problems and re-run it.
When smartinstall completes with no errors, you can continue on to the next step. It will print the URL that you can visit to test your configuration.
Select some non-destructive examples (like copying a CD to a directory or a raw partition), and make sure that they work. To test burning a CD, select ``Advanced Options'' on the first screen, and set ``Use test mode'' to ``Yes''.
How you do this will depend on your Webserver. With Apache, you probably want to use .htaccess files to control this; for other servers, consult the documentation for your server.
Here's an easy way to configure access control under Apache; for more information, see Apache's documentation (at http://www.apache.org). This assumes that you have chosen the default locations for installation; if you haven't, change the locations appropriately.
AllowOverride Limit AuthConfig [maybe others]
and an
AccessFileName .htaccess
command for both the html and cgi-bin directories you are installing in, or for the entire server. If there isn't, add one:
<Directory "/path/to/httpd/cgi-bin/cgiburn">
AllowOverride Limit AuthConfig
AccessFileName .htaccess
</Directory>
<Directory "/path/to/httpd/html/cgiburn">
AllowOverride Limit AuthConfig
AccessFileName .htaccess
</Directory>
So, edit /path/to/httpd/cgi-data/cgiburn/htaccess, and restrict the access how you need to. Your file should start with
Deny from all
as the default access.
Then, to restrict access by domain name (your Apache must be compiled with this option) or IP address, add
Allow from 1.2.3
to allow 1.2.3.*, or
Allow from .my.dom
to allow *.my.dom.
To restrict access by passwords, add
AuthType Basic AuthUserFile /path/to/httpd/cgi-data/cgiburn/htpasswd AuthName "cgiburn" Require valid-user
then add an account for username by typing
htpasswd -c /path/to/httpd/cgi-data/cgiburn/htpasswd username
The -c flag creates the file; after that, add new users by typing
htpasswd /path/to/httpd/cgi-data/cgiburn/htpasswd anotheruser
If you want to grant access to some addresses, and require everyone else to enter a password, use both of those commands, then put
Satisfy any
at the end of your configuration. This requires Apache 1.3.x or newer.
For example, an htaccess file which would allow anybody on a local 10.* network access for free, and require everyone else to supply a password, might look like:
Deny from all Allow from 10.0.0.100 AuthType Basic AuthUserFile /var/home/httpd/cgi-data/cgiburn4/htpasswd AuthName "cgiburn" Require valid-user Satisfy any
cd /path/to/httpd ln -s html/cgiburn/.htaccess /path/to/html/cgi-data/cgiburn/htaccess ln -s cgi-bin/cgiburn/.htaccess /path/to/html/cgi-data/cgiburn/htaccess
Once you have done this, you can be sure that only people you want to use will be operating CGIBurn.
For advanced users, smartinstall has two special options: -i does an ``in-place install'', fixing -I lines, creating configuration caches, etc., without actually copying any
files anywhere. In conjunction with an edited configuration and Webserver
configuration, you can use this to keep all of CGIBurn together. -l does a ``symlink install''. It does the same thing as -i, then makes symlinks from all of the places it would normally install
files into the source directory. This is very useful for doing active
development of CGIBurn, or for getting the tidiness of an ``all in one
place'' install, with the convenience of your Webserver just working.
If you choose either of these advanced options, you should expect to spend some time getting your configuration tweaked. smartinstall will not try to set permissions correctly on anything, so you will need to make sure your Webserver can read and write where it needs to.
Because CGIBurn is an interface for users connecting over an unprotected channel (the Web) to devices on your system which require root privileges, it sits on a security boundary, and a serious bug in it could become a bug which lets a cracker take control of your system. I have tried very hard to make sure no bugs like this exist, but I can't guarantee they don't.
I have taken a number of steps to make it as unlikely as possible that a bug like this could occur.
The hipri|bin-hipri script is a notable exception, which raises its own priority, then execs
another process with this raised priority. It is designed to be as short as
possible, to include no bells and whistles which could compromise security,
and to only be able to run programs in a specific directory (configured by
you). It is also installed by default so that only the Webserver's group
can execute it; having your Webserver run in a group that only it is in
will help protect hipri from other services or users on a multipurpose or
multiuser machine.
The other exceptions are the tools that are used by the various driver programs. Some of these, like mount(1) and cdrecord(1), will need to be installed setuid to root in order for the Webserver user to use them. The driver modules are very careful not to pass along anything directly from the user, which should prevent most of these bugs.
All programs that interact directly with the user use taint checking carefully, to make sure that no user-supplied data is used in a dangerous way. Specifically, no user-supplied data is used directly in executing anything, and all files that are operated on by user-supplied data are confined to specific directories.
The interactions between various components are straightforward, and are explained in the code and the documentation. That makes it less likely that security bugs will be introduced, and makes it easier for you or other people to audit the code for these types of bugs
In addition to this, there are some steps you can take to make CGIBurn more secure:
If the maching running CGIBurn is behind a firewall or a secure NAT router, you're all set; only people on the trusted side of your network can access CGIBurn at all, and they have much easier ways of breaking into your computers.
Otherwuse, using the instructions under INSTALLING, limit access to CGIBurn to specific IP addresses, or protect it with user passwords. Making sure that no malicious users can even get to CGIBurn helps ensure they can't try to make it misbehave.
This also protects you from inappropriate users manipulating your CDR drive, interrupting your burns and generally being irritating.
If you put the Webserver user in its own group, you can configure your system so that only that group has access to any setuid CGIBurn programs, like hipri or cdrecord(1). Just make the programs owned by the Webserver user's group, and remove all access to them from other people, like this:
chgrp webgroup /path/to/hipri /path/to/cdrecord chmod o= /path/to/hipri /path/to/cdrecord
On multipurpose and or multiuser systems, this protects you from other users on the system trying to use CGIBurn's privileged programs inappropriately.
If you have users uploading CGI scripts which will run with the same privileges as your Webserver (and would therefore have access to these programs), you might want to consider starting up a second copy of your Webserver exclusively for CGIBurn, on a different port or IP address.
CGIBurn is copyright 2000 by Scott Gifford.
It comes with absolutely no warranty.
It is licensed under the GPL; see the included file COPYING for details.
CONFIG, TEMPLATES, HACKING, COPYING.
$Id: README.pod,v 402.1 2001/02/05 11:43:30 sgifford Exp $