Parent Directory
| 
Revision Log
rid of double ## on copyright: reserved for Doxygen; add: Doxygen props
mod_tex 0.1-beta README
Peter Danenberg <pcd at wikitex dot org>
http://wikisophia.org
ABSTRACT
README covers hortation and installation.
14 February 2007
README -i- mod_tex 0.1-beta
Table of Contents
0. Prerequisites . . . . . . . . . . . . . . . . . . . 1
1. Installation . . . . . . . . . . . . . . . . . . . . 1
1.1. Server . . . . . . . . . . . . . . . . . . . 1
1.2. Handler . . . . . . . . . . . . . . . . . . . 2
2. Execution . . . . . . . . . . . . . . . . . . . . . 2
3. Configuration . . . . . . . . . . . . . . . . . . . 2
3.1. Directories . . . . . . . . . . . . . . . . . 2
3.2. Users . . . . . . . . . . . . . . . . . . . . 2
3.3. Facilities . . . . . . . . . . . . . . . . . 3
3.4. Resources . . . . . . . . . . . . . . . . . . 3
3.4.1. Internal . . . . . . . . . . . . . . . 3
3.4.2. Kernel-Enforced . . . . . . . . . . . 3
3.4.3. Per-User . . . . . . . . . . . . . . . 3
4. Chroot . . . . . . . . . . . . . . . . . . . . . . . 3
4.1. LaTeX . . . . . . . . . . . . . . . . . . . . 4
4.2. Gnuplot . . . . . . . . . . . . . . . . . . . 5
4.3. LilyPond . . . . . . . . . . . . . . . . . . 5
4.4. Graphviz . . . . . . . . . . . . . . . . . . 6
4.5. sgf2dg . . . . . . . . . . . . . . . . . . . 6
5. Architecture . . . . . . . . . . . . . . . . . . . . 6
6. Copyright . . . . . . . . . . . . . . . . . . . . . 7
7. Colophon . . . . . . . . . . . . . . . . . . . . . . 7
14 February 2007
README -1- mod_tex 0.1-beta
mod_tex 0.1-beta README
Peter Danenberg <pcd at wikitex dot org>
http://wikisophia.org
0. Prerequisites
o Apache
o mod_python
o Python 2.5
o LaTeX, dvipng, etc.[1]
1. Installation
1.1. Server
1. Copy src/server/modtex/config/default.py to:
src/server/modtex/config/local.py
2. Edit local.py to satisfaction.[2]
3. Create user `modtex' and `modtex'-group.[3]
4. Mount a file system on /usr/local/var/modtex
with NOSUID (optional).
5. Run:
python setup.py build
and:
sudo python setup.py install
6. Set up as many chroot environments in
/usr/local/var/modtex as you'd like to sup-
port.[4]
-----------
1. See section 4, Chroot; the number of depen-
dencies is proportional to the number of packages
you'd like to support.
2. See section 3, Configuration.
3. Or whatever user and group was provided in
`local.py'.
4. See section 4, Chroot.
14 February 2007
README -2- mod_tex 0.1-beta
1.2. Handler
The Apache-handler mediates between the
client and chrooted daemons; it requires
mod_python.
1. Install mod_python,[5] if necessary.
2. You may need to edit the .htaccess which was
installed, by default, in:
/usr/local/apache2/htdocs/modtex/.htaccess
2. Execution
`modtex' and `modtex-debug' are installed by
default in /usr/local/bin. They both take `start' and
`stop' as arguments, but `modtex-debug' provides some
additional output to the syslog and keeps all work
directories intact in /usr/local/var/modtex/<root>/tmp
for inspection.
`modtex-debug' also refrains from setting resource
limits, since setting resource limits can introduce
anti-intuitive errors and must be done with care.
`modtex', on the other hand, cleans up work direc-
tories (except in cases of resource-faults); and prints
minimally to syslog.
`modtex' and `modtex-debug' need to be run as root
to chroot into the rendering environment, but drop
privileges immediately to modtex:modtex.
3. Configuration
3.1. Directories
mod_tex allows relatively fine-tuned control
over the install-location, and provides some rea-
sonable defaults.
3.2. Users
mod_tex also allows the ability to specify
the nonprivileged user to whom it will drop after
detaching from the console; it should be distinct
from the Apache user, and ideally ad-hoc.
-----------
5. http://www.modpython.org
14 February 2007
README -3- mod_tex 0.1-beta
3.3. Facilities
Please inspect the facilities section to make
sure that they correspond to your chroot environ-
ment; in particular, you will need to specify
absolute paths to binaries.
3.4. Resources
mod_tex's resource managament has three lay-
ers: internal, kernel-enforced and per-user.
3.4.1. Internal
The `default_wait' dictionary provides
fine-grained control over signals sent to
runaway processes; `default_wait' works over
and above RLIMIT_CPU, whose effects can be
hard to predict.
3.4.2. Kernel-Enforced
Read more about kernel-limits in `man
setrlimit'; mod_tex includes fairly Draconian
policies which may need to be relaxed for
production-sites.
3.4.3. Per-User
`ctime_unit' and `max_ctime_per_unit'
provide ways to limit resource-usage from
particular users. mod_tex calculates how
much CPU-time a user has usurped within one
`ctime_unit'; if its usage exceeds
`max_ctime_per_unit' with that unit of time,
the request is temporarily denied.
The upshot is that users may have to
submit several requests to complete a partic-
ularly time-consuming document.
4. Chroot
Chrooting is art and science; and can be risky if,
for instance, you leave suid-binaries lying around.
Modtex provides jailkit.ini in `src/jailkit'
which, when used with Olivier Sessink's Jailkit,[6] can
help with the mechanics of chrooting.
Here's a mapping of actions to entities, for which
see the relevant sections below:
-----------
6. http://olivier.sessink.nl/jailkit
14 February 2007
README -4- mod_tex 0.1-beta
Table 4.1. Actions and entities
--------------------------------
Action Entity
--------------------------------
chemistry LaTeX
chess LaTeX
Feynman diagrams LaTeX
go sgf2dg
graphs Graphviz
math LaTeX
music LilyPond
plotting Gnuplot
--------------------------------
Each jailed entity has prerequisite software, and
relevant sections of `jailkit.ini'.
Nota bene: ld.so.cache is not automatically copied
to the root, and needs to be rebuilt by running
/sbin/ldconfig from within the root after installation.
Nota item bene: `jailkit.ini' assumes that most
packages were build with `--enable-static'; YMMV.
4.1. LaTeX
Prerequisites:
LaTeX,[7] dvipng,[8] FreeType[9]
Jailkits:
latex, mktexpk, shell[10], dvipng, freetype
Additional packages:
Table 4.1.1. Additional packages
------------------------------------------------------
Action Package Site Included[a]
------------------------------------------------------
chem XyMTeX imt.chem.kit.ac.jp
chess skak ctan.org *
-----------
7. TeX Live (http://www.tug.org/texlive) has
superseded teTeX (http://www.tug.org/tetex).
8. http://sourceforge.net/projects/dvipng
9. For best results, enable the byte-code inter-
preter. http://www.freetype.org
10. `mktexpk', unfortunately, requires a shell;
if you can build the requisite PK files by manu-
ally chrooting into the environment, however, you
may be able to dispense with the shell.
Try generating the PKs by running a test-case
through latex and dvipng.
14 February 2007
README -5- mod_tex 0.1-beta
Table 4.1.1. Additional packages
------------------------------------------------------
skaknew ctan.org *
texmate ctan.org *
feyn FeynMF ctan.org *
math AMS-LaTeX ams.org *
------------------------------------------------------
a. May be included in TeX Live.
Edit `texmf.cnf' within the chroot, modifying
the following variables:
shell_escape = f
openout_any = p
openin_any = p
Don't forget to manually run `texhash' and
`updmap' from within the chroot.
4.2. Gnuplot
Prerequisites:
Gnuplot,[11] Fontconfig[12]
Jailkits:
gnuplot, fontconfig, fonts
IMPORTANT: disable system-calls in Gnuplot by
applying the patch found in `src/patches'; from
Gnuplot's source directory, issue:
patch -p1 < gnuplot-4.0.0-no-system.patch
Then build normally.
4.3. LilyPond
Prerequisites:
LilyPond,[13] Guile,[14] Fontconfig,[15]
Pango,[16] Ghostscript[17]
Jailkits:
guile, fontconfig, pango, ghostscript, fonts
-----------
11. http://www.gnuplot.info
12. http://www.fontconfig.org
13. http://lilypond.org
14. http://www.gnu.org/software/guile/guile.html
15. http://www.fontconfig.org
16. http://www.pango.org
17. http://www.cs.wisc.edu/~ghost
14 February 2007
README -6- mod_tex 0.1-beta
For building LilyPond, there are more requi-
sites; see `INSTALL.txt'.
4.4. Graphviz
Prerequisites:
Graphviz,[18] Pango,[19] Fontconfig[20]
Jailkits:
pango, fontconfig, fonts
`dot' should be linked to `dot_static' before
installation (provided that you built with
`--enable-static').
4.5. sgf2dg
Prerequisites:
sgf2dg,[21] LaTeX,[22] Perl[23]
Jailkits:
latex, perl, dvipng, mktexpk
Since Perl is a significant requirement over
and above basic LaTeX packages, we decided to
install sgf2dg in its own root for people willing
to incur the cost.
5. Architecture
In short, an XML-RPC client (e.g., the MediaWiki-
client) connects to the mod_python frontend ("Trader
Joe") served by Apache.
Trader Joe, in turn, connects to autonomous,
unprivileged, chrooted daemons sitting on arbitrary
machines, that actually render the content.
After authentication,[24] but before Trader Joe
befrays the rendering drones, he checks an IP->CPU-time
database to see whether the client has used up their
allotted rendering time.
-----------
18. http://www.graphviz.org
19. http://www.pango.org
20. http://www.fontconfig.org
21. http://match.stanford.edu/bump/go.html
22. TeX Live (http://www.tug.org/texlive) has
superseded teTeX (http://www.tug.org/tetex).
23. http://www.perl.com
24. Trader Joe uses basic-, but key-based-auth
should be possible using curl's transport-layer.
14 February 2007
README -7- mod_tex 0.1-beta
LaTeX-daemon
/
client<--(auth)-->traderjoe<--(resource)-->LilyPond-daemon
\
...-daemon
The daemons should not be accessible to the intar-
web at large.
6. Copyright
mod_tex: distributed LaTeX-rendering over Apache
Copyright (C) 2007 Peter Danenberg
You should have received a copy of the GNU General
Public License version 2 along with this program; if
not, write to the Free Software Foundation, Inc., 51
Franklin Street, Fifth Floor, Boston, MA 02110-1301,
USA.
7. Colophon
This document was prepared in GNU troff using the
ms macro package; preprocessed with tbl, the table for-
matter; and lastly filtered through col to remove
reverse line feeds and tabs:
groff -ms -t -Tascii SOURCE | col -bx > OUT
Automatically generated contents were moved from page
last to first with an ad-hoc bash-diddy.
14 February 2007
| Peter Danenberg <pcd at modtex dot org> | ViewVC Help |
| Powered by ViewVC 1.1-dev |