[Refdb-cvs] CVS: refdb/doc refdb-manual-chapter14.sgml,1.9.2.1,1.9.2.2 refdb-manual-chapter2.sgml,1.
Status: Beta
Brought to you by:
mhoenicka
Menu
▾
▴
[Refdb-cvs] CVS: refdb/doc refdb-manual-chapter14.sgml,1.9.2.1,1.9.2.2 refdb-manual-chapter2.sgml,1.15.2.1,1.15.2.2 refdb-manual-chapter5.sgml,1.24.2.1,1.24.2.2 refdb-manual-chapter8.sgml,1.13.2.1,1.13.2.2 refdb-manual-configopts.sgml,1.4.2.1,1.4.2.2
|
From: Markus H. <mho...@us...> - 2004-11-25 21:28:52
|
Update of /cvsroot/refdb/refdb/doc In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv32032/doc Modified Files: Tag: Release_0_9_5_stable refdb-manual-chapter14.sgml refdb-manual-chapter2.sgml refdb-manual-chapter5.sgml refdb-manual-chapter8.sgml refdb-manual-configopts.sgml Log Message: updated for 0.9.5 Index: refdb-manual-chapter14.sgml =================================================================== RCS file: /cvsroot/refdb/refdb/doc/refdb-manual-chapter14.sgml,v retrieving revision 1.9.2.1 retrieving revision 1.9.2.2 diff -u -U2 -r1.9.2.1 -r1.9.2.2 --- refdb-manual-chapter14.sgml 14 Nov 2004 16:04:49 -0000 1.9.2.1 +++ refdb-manual-chapter14.sgml 25 Nov 2004 21:28:41 -0000 1.9.2.2 @@ -38,6 +38,6 @@ <arg choice="req" rep="norepeat">database</arg> <arg choice="req" rep="norepeat">style</arg> - <arg choice="opt" rep="norepeat">encoding</arg> - <arg choice="opt" rep="norepeat">css-file</arg> + <arg choice="req" rep="norepeat">encoding</arg> + <arg choice="req" rep="norepeat">css-file</arg> </cmdsynopsis> <para>The script will create two files in your current working directory:</para> Index: refdb-manual-chapter2.sgml =================================================================== RCS file: /cvsroot/refdb/refdb/doc/refdb-manual-chapter2.sgml,v retrieving revision 1.15.2.1 retrieving revision 1.15.2.2 diff -u -U2 -r1.15.2.1 -r1.15.2.2 --- refdb-manual-chapter2.sgml 14 Nov 2004 16:04:49 -0000 1.15.2.1 +++ refdb-manual-chapter2.sgml 25 Nov 2004 21:28:41 -0000 1.15.2.2 @@ -22,5 +22,5 @@ </listitem> <listitem> - <para>Solaris</para> + <para>Solaris/SunOS</para> </listitem> <listitem> @@ -159,7 +159,7 @@ </varlistentry> <varlistentry> - <term>XSL processor (required for DocBook and TEI XML documents)</term> + <term>XSLT and FO processors (required for DocBook and TEI XML documents)</term> <listitem> - <para>If you're working with XML documents and want to transform them using the XSL stylesheets, you'll need some sort of XSL processing machinery. Popular choices are <ulink url="http://xml.apache.org">Xalan</ulink>, <ulink url="http://saxon.sourceforge.net">Saxon</ulink>, and <ulink url="http://xmlsoft.org/XSLT">xsltproc</ulink>. The latter is checked for in the configure script and will be used as the default processor if available. The Java-based tools among these need the <ulink url="http://java.sun.com">Java Virtual Machine</ulink> installed, of course. Generating printable output seems to work best with <ulink url="http://xml.apache.org/fop/index.html">FOP</ulink>.</para> + <para>If you're working with XML documents and want to transform them using the XSL stylesheets, you'll need some sort of XSL processing machinery. Popular choices are <ulink url="http://xml.apache.org">Xalan</ulink>, <ulink url="http://saxon.sourceforge.net">Saxon</ulink>, and <ulink url="http://xmlsoft.org/XSLT">xsltproc</ulink>. The latter is checked for in the configure script and will be used as the default processor if available. The Java-based tools among these need the <ulink url="http://java.sun.com">Java Virtual Machine</ulink> installed, of course. Generating printable output from FO seems to work best with <ulink url="http://xml.apache.org/fop/index.html">FOP</ulink>.</para> </listitem> </varlistentry> Index: refdb-manual-chapter5.sgml =================================================================== RCS file: /cvsroot/refdb/refdb/doc/refdb-manual-chapter5.sgml,v retrieving revision 1.24.2.1 retrieving revision 1.24.2.2 diff -u -U2 -r1.24.2.1 -r1.24.2.2 --- refdb-manual-chapter5.sgml 14 Nov 2004 16:04:50 -0000 1.24.2.1 +++ refdb-manual-chapter5.sgml 25 Nov 2004 21:28:41 -0000 1.24.2.2 @@ -43,5 +43,5 @@ <para>Once again, the database schema of the main database has changed. However, starting from this version the name of the main database is a configure option. If you do not have to run this and an older version in parallel, you don't have to change the configuration. However, if you want to keep your existing setup while test-driving the new version, there is a new configure switch <option>--with-main-db</option> to set the name of the main database.</para> <para>In the first case, you'll have to replace your existing main database with the new version. In the second case, you create another main database with a different name. Only the new version of &appname; will be able to access this database if configured properly.</para> - <para>Finally, a bug in the MySQL table definitions was fixed. If you're using MySQL as your database engine, you'll have to dump your data and re-create your reference databases with the new version installed. See the instructions about migrating your data to 0.9.4. With this version it is also safe to use risx as the dump format.</para> + <para>Finally, a bug in the MySQL table definitions was fixed. If you're using MySQL as your database engine, you'll have to migrate your reference databases as well. 0.9.5 provides a SQL script that changes the table definitions appropriately.</para> </listitem> <listitem> @@ -213,5 +213,5 @@ <sect3> <title>Types of configuration files</title> - <para>All &appname; applications and scripts that use configuration files (these are the server <link linkend="chapter-refdbd">&appname;d</link>, the clients <link linkend="chapter-refdbc">&appname;c</link>, <link linkend="chapter-refdbib">&appname;ib</link>, <link linkend="chapter-refdba">&appname;a</link>, as well as the conversion filters <link linkend="sect-bibtoris">bib2ris</link>, <link linkend="sect-dbtoris">db2ris</link>, <link linkend="sect-medtorispl">med2ris.pl</link>, <link linkend="sect-marctoris">marc2ris.pl</link>, and <link linkend="sect-entorispl">en2ris.pl</link>) can use two configuration files each. One global configuration file is supplied by the system administrator and can be used to set values that are common for all users on that box, like the IP address of the application server. Another file can be used by every user to supply the values that were not set in the global file or to override settings in this file. The users' copies can have a leading dot to hide the files (the &appname; programs will first try to read a hidden configuration file, and only if that cannot be found they try to read a non-hidden file).</para> + <para>All &appname; applications and scripts that use configuration files (these are the server <link linkend="chapter-refdbd">&appname;d</link>, the clients <link linkend="chapter-refdbc">&appname;c</link>, <link linkend="chapter-refdbib">&appname;ib</link>, <link linkend="chapter-refdba">&appname;a</link>, the script <link linkend="sect2-refdbxml-init-variables">&appname;xml</link>, as well as the conversion filters <link linkend="sect-bibtoris">bib2ris</link>, <link linkend="sect-dbtoris">db2ris</link>, <link linkend="sect-medtorispl">med2ris.pl</link>, <link linkend="sect-marctoris">marc2ris.pl</link>, and <link linkend="sect-entorispl">en2ris.pl</link>) can use two configuration files each. One global configuration file is supplied by the system administrator and can be used to set values that are common for all users on that box, like the IP address of the application server. Another file can be used by every user to supply the values that were not set in the global file or to override settings in this file. The users' copies can have a leading dot to hide the files (the &appname; programs will first try to read a hidden configuration file, and only if that cannot be found they try to read a non-hidden file).</para> <para>&appname;c, bib2ris, marc2ris.pl, and med2ris.pl use a second global configuration file if they are run as a CGI applications. A local configuration file does not make sense in this case.</para> <para>The default location for the global configuration files is <filename>/usr/local/etc/refdb</filename>. There are two ways to change this. If you compile &appname; from the sources you can specify a different directory with the <option>--prefix</option> or <option>--sysconfdir</option> options of <command moreinfo="none">./configure</command>. E.g. if you specify <option>--sysconfdir=/etc</option>, then the configuration files will be installed in <filename class="directory" moreinfo="none">/etc/&appname;</filename> (the <filename moreinfo="none">&appname;</filename> part is automatically appended by the &appname; install routines). If you use precompiled binaries, use the <option>-y</option> command line option to specify the directory. In this case you have to specify the full path, i.e. <filename class="directory" moreinfo="none">/etc/refdb</filename> to read the configuration files installed by the previous example.</para> @@ -431,13 +431,13 @@ <step performance="required"> <para>Run the following command (adapt this accordingly if you use some graphical CVS frontend instead of the command line tool):</para> - <screen format="linespecific"><prompt moreinfo="none">$~/build </prompt><userinput moreinfo="none">cvs -d :pserver:ano...@cv...:/cvsroot/refdb login</userinput></screen> + <screen format="linespecific"><prompt moreinfo="none">$~/build </prompt><userinput moreinfo="none">cvs -d :pserver:ano...@cv...:/cvsroot/refdb login</userinput></screen> <para>Just press enter if you're asked for a password. This login is required only once as CVS will remember the required information for all later accesses.</para> </step> <step performance="required"> <para>Check out the latest &appname; sources with this command:</para> - <screen format="linespecific"><prompt moreinfo="none">$~/build </prompt><userinput moreinfo="none">cvs -d :pserver:ano...@cv...:/cvsroot/refdb -z3 checkout refdb</userinput></screen> + <screen format="linespecific"><prompt moreinfo="none">$~/build </prompt><userinput moreinfo="none">cvs -d :pserver:ano...@cv...:/cvsroot/refdb -z3 checkout refdb</userinput></screen> <para>Other interesting modules are <filename>perlmod</filename> (the Perl modules and the Perl client library) and <filename>elisp</filename> (the Emacs support files).</para> <para>If you are interested in a particular release or branch, use a command along the lines of this example instead:</para> - <screen format="linespecific"><prompt moreinfo="none">$~/build </prompt><userinput moreinfo="none">cvs -d :pserver:ano...@cv...:/cvsroot/refdb -z3 checkout -r Release_0_9_1 refdb</userinput></screen> + <screen format="linespecific"><prompt moreinfo="none">$~/build </prompt><userinput moreinfo="none">cvs -d :pserver:ano...@cv...:/cvsroot/refdb -z3 checkout -r Release_0_9_1 refdb</userinput></screen> </step> <step performance="required"> @@ -701,5 +701,5 @@ <title>PostgreSQL</title> <note> - <para>If <filename>postmaster</filename> (the PostgreSQL database server) is installed on a remote box or if the security settings require it, you may have to use the <option>-h <replaceable>hostname</replaceable></option> and/or the <option>-U <replaceable>username</replaceable></option> options to run the <filename>psql</filename> client as shown below (most fresh PostgreSQL installations on Unix-style systems use "pgsql" with no password as the default database administrator. The Cygwin port of PostgreSQL uses the name of whoever installed the package, usually "Administrator"). <filename>postmaster</filename> needs to be up and running and you need the appropriate permissions, of course. See the <application>PostgreSQL</application> documentation for further details.</para> + <para>If <filename>postmaster</filename> (the PostgreSQL database server) is installed on a remote box or if the security settings require it, you may have to use the <option>-h <replaceable>hostname</replaceable></option> and/or the <option>-U <replaceable>username</replaceable></option> options to run the <filename>psql</filename> client as shown below (most fresh PostgreSQL installations on Unix-style systems use "pgsql" with no password as the default database administrator. The Cygwin port of PostgreSQL uses the name of whoever installed the package, usually "Administrator". On Debian you need to be logged in as user "postgres": first <command moreinfo="none">su root</command>, then <command moreinfo="none">su postgres</command>). <filename>postmaster</filename> needs to be up and running and you need the appropriate permissions, of course. See the <application>PostgreSQL</application> documentation for further details.</para> </note> <itemizedlist> @@ -816,322 +816,4 @@ <para>This is all it takes to test the basic functionality of your setup. Everything beyond this is either site-specific setup or mere usage of the tools. Please peruse the manual, especially the hints about getting your <link linkend="sect-database-server-access-control">database access rights</link> correct.</para> </sect1> - <sect1> - <title>Setting up the &appname; web services</title> - <para>This section guides you through the necessary steps to run &appname;c, bib2ris, and med2ris.pl as <acronym>CGI</acronym> applications. This will allow the users to enjoy a part of the functionality of &appname; through a web interface.</para> - <para>If you want to work through this section you'll need some basic knowledge about the administration of your web server. Needless to say that you also need the proper privileges to fiddle with your web server settings. The procedure below was written with <ulink url="http://www.apache.org">Apache</ulink> 1.3 on Debian GNU/Linux in mind. Apache is by far the most popular web server and available on various platforms, including all platforms that &appname; currently supports. If you use a different Linux distribution or a different operating system, the location and name of the files may slightly differ. If you use a different web server, the configuration process may be entirely different, but with the user manual at your hands you may be able to adapt the following instructions to your needs.</para> - <note> - <para>If your web server and the &appname;d application server run on different machines, please notice that all but one steps below talk about the computer running the web server. One step talks about the computer running &appname;d.</para> - </note> - <procedure> - <step performance="required"> - <para>To tell Apache about the &appname; web pages, add the following line to <filename>/etc/apache/httpd.conf</filename>:</para> - <programlisting format="linespecific"> -Alias /refdb/ /usr/local/share/refdb/www/ -</programlisting> - <para>This entry will let you access the &appname; web interface through the address [hostname]/refdb. While you're at modifying <filename moreinfo="none">httpd.conf</filename>, the next step may require another change to this file.</para> - </step> - <step performance="required"> - <para>Most web servers expect CGI applications in one specific, configurable directory. If your web server is not already set up for CGI applications, you`ll have to register a cgi-bin directory. To do this in the case of Apache, add the following line to <filename>/etc/apache/httpd.conf</filename>:</para> - <programlisting> -ScriptAlias /cgi-bin/ /usr/local/bin/apache/cgi-bin/ -</programlisting> - <para>You can of course choose a different directory if you wish.</para> - <para>The directory must be readable and accessible for the account that the web server daemon runs in (this is often user "www" and group "www", which I will use in the example below). If this is not already the case, issue something like the following commands:</para> - <screen format="linespecific"><prompt moreinfo="none">#~ </prompt><userinput moreinfo="none">chown www:www /usr/local/bin/apache/cgi-bin</userinput></screen> - <screen><prompt>#~ </prompt><userinput>chmod u+rx /usr/local/bin/apache/cgi-bin</userinput></screen> - <para>Now you have to tell Apache about the updated configuration:</para> - <screen><prompt>#~ </prompt><userinput>apachectl restart</userinput></screen> - </step> - <step performance="required"> - <para>Place copies of <filename>&appname;c</filename>, <filename>bib2ris</filename>, and <filename>med2ris.pl</filename> in your <filename class="directory">/cgi-bin</filename> directory. Unless they are readable and executable for everyone you'll have to make them read/executable for the web server daemon:</para> - <screen format="linespecific"><prompt moreinfo="none">#~ </prompt><userinput moreinfo="none">cd /usr/local/bin/apache/cgi-bin/</userinput></screen> - <screen format="linespecific"><prompt moreinfo="none">#~ </prompt><userinput moreinfo="none">chown www:www &appname;c bib2ris med2ris.pl</userinput></screen> - <screen><prompt>#~ </prompt><userinput>chmod u+rx &appname;c bib2ris med2ris.pl</userinput></screen> - </step> - <step performance="required"> - <para>Create the <link linkend="sect1-mystery-init-files">configuration files</link> <filename>/usr/local/etc/&appname;/&appname;cgirc</filename>, <filename>/usr/local/etc/&appname;/bib2riscgirc</filename>, and <filename>/usr/local/etc/&appname;/med2riscgirc</filename> (unless you chose a different directory during configuration) and fill in appropriate values. Remember that bib2ris and med2ris need access to HTML templates. You should specify the proper value for &appname;lib in the configuration files.</para> - </step> - <step> - <para>You can of course <link linkend="ch-customize-web">modify the HTML files and the stylesheet</link> according to your needs. The static HTML files, a CSS stylesheet file, and a JavaScript file are installed by default in <filename class="directory">/usr/local/share/refdb/www</filename>, whereas the HTML templates are installed in <filename class="directory">/usr/local/share/refdb/templates</filename> <emphasis>on the computer that runs &appname;d</emphasis>. Both the computer that runs Apache and the CGI programs and the computer that runs &appname;d need a copy of <filename class="directory">/usr/local/share/refdb/templates</filename>.</para> - </step> - <step> - <para>The file <filename>refdbquery.html</filename> is the main entry point to the &appname; web interface. Web visitors should be guided to this page as it allows username/password authentication. The &appname; installation procedure creates a symlink with the name <filename moreinfo="none">index.html</filename> pointing to <filename>refdbquery.html</filename>, so you'll be able to access the main query page by pointing your browser to "[hostname]/refdb/".Provide links on your web pages accordingly.</para> - </step> - </procedure> - <para>It may be a good idea to check the access rights of all related files again to make sure the site visitors can access them from their browser. The static HTML pages, the templates, the javascript file, and the CSS style sheet must be readable for the account the web server is started under. The templates must be readable for the account &appname;d is started under.</para> - </sect1> - <sect1> - <title>Logging data</title> - <para>The &appname; programs can spill out quite a lot of log messages to keep track of what is happening in your programs. This section explains the basics of setting up your message logging.</para> - <sect2> - <title>What to log</title> - <para>The application server &appname;d as well as all command-line clients can generate log messages. Message logging is most important for two purposes:</para> - <itemizedlist> - <listitem> - <para>Keep track of non-interactive programs. This includes &appname;d as well as &appname;c, bib2ris, and nmed2ris if they are run as CGI applications. It may include all clients if they are run from scripts.</para> - </listitem> - <listitem> - <para>Track down bugs or user errors.</para> - </listitem> - </itemizedlist> - <para>A useful approach is to log all messages with a log level (explained <link linkend="sect2-log-level">below</link>) of 6. This would give you a good overview over the usage of these programs but would not clutter the log files with debug information. Switch to log level 7 only if you suspect a bug or some user error and need the full debug information to understand the problem.</para> - <para>For the interactive use of the clients logging is usually not necessary, so you'd use a log level of -1 to prevent logging altogether or a log level of maybe 3 or 4. In the latter case you'd get log messages only if something goes badly wrong. Again, if you encounter bugs or user errors you may switch on debug messages by using a log level of 7.</para> - </sect2> - <sect2> - <title>Destinations</title> - <para>There are three possible destinations the log messages can be sent to. Select the proper destination with either the <varname>logdest</varname> variable in the configuration file or the <option>-e</option> switch on the command line. In both cases the values in the following list are accepted. You may use either the numerical value or the case-insensitive string in brackets, e.g. <option>-e 1</option> and <option>-e syslog</option> are equivalent.</para> - <variablelist> - <varlistentry> - <term>0 (stderr)</term> - <listitem> - <para>stderr is mostly useful for debugging purposes when &appname;d is run as a standalone process and when clients are run interactively. stderr does not make much sense if you run &appname;d as a daemon (daemons detach from the console at startup, so all output to stderr is lost).</para> - </listitem> - </varlistentry> - <varlistentry> - <term>1 (syslog)</term> - <listitem> - <para>Sending the data to syslog integrates the log data with the rest of your system's log output. The log messages will be sent to the user facility, which usually is configured to write to <filename>/var/log/user.log</filename>. See the syslog(8) man page for information how to configure the syslog facility.</para> - <note> - <para>If you run &appname;d on Cygwin, the syslog messages are sent to the application message list in the NT message logging system. If you are used to going through your log output with tools like grep and awk, you may find it more useful to write to a custom log file instead.</para> - </note> - </listitem> - </varlistentry> - <varlistentry> - <term>2 (file)</term> - <listitem> - <para>You can define the full path of a custom log file with either the <varname>logfile</varname> configuration file parameter or the <option>-L</option> command line option. By default, &appname; applications write their log output to <filename>/var/log/<appname>.log</filename>. Make sure to set the appropriate access rights for these log files.</para> - </listitem> - </varlistentry> - </variablelist> - <note> - <para>Some libraries used by &appname;, e.g. the PostgreSQL client library, send log messages to stderr. This is not controlled by the log settings of &appname;d. The same PostgreSQL log messages show up in the PostgreSQL log which is usually sent to <filename moreinfo="none">/var/log/pgsql</filename>.</para> - </note> - </sect2> - <sect2 id="sect2-log-level"> - <title>Log levels</title> - <para>You can select how verbose the log output of &appname;d will be. You can do this by either setting the <varname>loglevel</varname> configuration file variable or the <option>-l</option> command line option to an appropriate value. You may either use the numerical value or the case-insensitive string as explained in the table below. E.g. <option>-l 5</option> and <option>-l notice</option> are equivalent. Set the log level to -1 to disable logging completely. Use a value from 0 through 7 to generate increasingly verbose log output. The definitions of the log levels are taken from the include file <filename>syslog.h</filename>:</para> - <table id="table-loglevel-definitions"> - <title>Log level definitions</title> - <tgroup cols="3"> - <thead> - <row> - <entry>level</entry> - <entry>verbose</entry> - <entry>explanation</entry> - </row> - </thead> - <tbody> - <row> - <entry>0</entry> - <entry>emerg</entry> - <entry>system is unusable</entry> - </row> - <row> - <entry>1</entry> - <entry>alert</entry> - <entry>action must be taken immediately</entry> - </row> - <row> - <entry>2</entry> - <entry>crit</entry> - <entry>the system is in a critical condition</entry> - </row> - <row> - <entry>3</entry> - <entry>err</entry> - <entry>there is an error condition</entry> - </row> - <row> - <entry>4</entry> - <entry>warning</entry> - <entry>there is a warning condition</entry> - </row> - <row> - <entry>5</entry> - <entry>notice</entry> - <entry>a normal but significant condition</entry> - </row> - <row> - <entry>6</entry> - <entry>info</entry> - <entry>a purely informational message</entry> - </row> - <row> - <entry>7</entry> - <entry>debug</entry> - <entry>messages generated to debug the application</entry> - </row> - </tbody> - </tgroup> - </table> - <para>Setting the log level to a given value means that all messages with a priority level up to the given value will be logged. E.g. if you set the log level to 6 (which is a reasonable default value), all messages with a priority from 0 through 6 will be logged, whereas messages with a priority level of 7 will be ignored.</para> - <warning> - <para>Use log level 7 with caution. The amount of log messages is considerable and sufficient to slow down the application. You should not use this level in everyday use, only to track down bugs or user errors that you may encounter.</para> - </warning> - </sect2> - <sect2> - <title>Interpreting the log information</title> - <para>If the messages are sent to stderr, only the message proper will be printed. If the messages are sent to the syslog facility, the default format including the process name and process ID is used.</para> - <para>A line in the custom log file looks like this:</para> - <programlisting>6:pid=267:Sun Jul 22 18:39:52 2001:application server started</programlisting> - <para>You will easily recognize the following fields:</para> - <programlisting>message_priority:process_id:time:message</programlisting> - <variablelist> - <varlistentry> - <term>message priority</term> - <listitem> - <para>This is the priority assigned to the message by &appname;d. The values are explained <link linkend="table-loglevel-definitions">above</link>.</para> - </listitem> - </varlistentry> - <varlistentry> - <term>process ID</term> - <listitem> - <para>This is the process ID (as seen in the <command>ps ax</command> listing) of the &appname; process that generated the message. In the case of &appname;d this may either be the parent process (the one that generated the above "application server started" message) or one of the children that are forked off to answer client requests.</para> - </listitem> - </varlistentry> - <varlistentry> - <term>time</term> - <listitem> - <para>This is the full time and date information when the message was generated.</para> - </listitem> - </varlistentry> - <varlistentry> - <term>message</term> - <listitem> - <para>This is the message text proper.</para> - </listitem> - </varlistentry> - </variablelist> - <para>The message entries are sufficiently structured to allow easy access to the information with the standard Unix tools like <application>awk</application> and <application>grep</application>.</para> - </sect2> - </sect1> - <sect1> - <title>Security issues</title> - <para>This section briefly discusses some security-related issues that you might want to think about as an administrator. We'll look at the access control provided by the external database servers MySQL and PostgreSQL.</para> - <note> - <para>The embedded database engine SQLite does not provide built-in access control. All you can do is use <command moreinfo="none">chown</command> and <command moreinfo="none">chmod</command> to restrict access to the database files. There is no way to restrict access through &appname;.</para> - </note> - <sect2> - <title>Passwords</title> - <para>&appname; tries to support the security features of the SQL database servers as far as possible. This includes the username/password-based access rights scheme (not much surprise here). Since version 0.6.0 the passwords are no longer transmitted as plain text between the clients and the server. This means that it now makes sense to keep the passwords secret. There are several ways to specify the password when starting a &appname; client. These ways differ with respect to the security of the passwords and are listed here in the order of <emphasis>increasing</emphasis> security:</para> - <variablelist> - <varlistentry> - <term>Specify the password on the command line</term> - <listitem> - <para>The password is stored nowhere on the filesystem and thus pretty secure from this point of view. But the full command line can be viewed with the <command moreinfo="none">ps</command> command by any user on the system, so the unencrypted password is basically world-readable at least for a very brief period until the applications have a chance to hide the string.</para> - </listitem> - </varlistentry> - <varlistentry> - <term>Store the password in the personal configuration file</term> - <listitem> - <para>This way the password is protected from other users who habitually run the <command moreinfo="none">ps</command> command just for the heck of it. But now it is stored unencrypted on the hard drive, and you must make sure that no one else can read the configuration file (no group or world read access).</para> - </listitem> - </varlistentry> - <varlistentry> - <term>Specify the password interactively</term> - <listitem> - <para>This is the default behaviour if the password is not specified either in the configuration file or on the command line. The &appname; client will ask for the password. This is certainly the most secure way to provide a password, but this won't work if you run the clients unattended via scripts.</para> - </listitem> - </varlistentry> - </variablelist> - </sect2> - <sect2 id="sect-database-server-access-control"> - <title>Database server access control</title> - <para>It is beyond the scope of this manual to reiterate the security models of the database servers, but you need to keep in mind a few aspects relevant to &appname;.</para> - <itemizedlist> - <listitem> - <para>One component of the database server access control is based on the host from which you connect to the database server. This is partially circumvented by the &appname; three-tier design. Keep in mind that only &appname;d communicates with the database server. Therefore only the host where &appname;d runs is relevant for the access control. There is currently no system in place for checking whether a client is allowed to connect to the &appname;d application server from a particular host.</para> - </listitem> - <listitem> - <para>Both MySQL and PostgreSQL distinguish between local and remote connections. Access needs to be granted separately if you want to use both local and remote connections</para> - <note> - <para>On many operating systems the default installations of MySQL and PostreSQL do not allow remote connections for security reasons. You need to manually allow remote connections as described below.</para> - </note> - </listitem> - <listitem> - <para>The &appname;a commands to remotely reconfigure a running application server are currently protected by a simple table access test. In any serious database server installation, only the database administators have read access to certain system tables. The current implementation of this check requires that you have access to this table if you want to run the <link linkend="app-admin-command-confserv"><command moreinfo="none">confserv</command></link> commands. You should be aware that if the access rights are set up improperly, you may also allow everyone and their grandma to stop or reconfigure the &appname;d application server. If you cannot restrict read access to system tables for whatever reason, you should not enable &appname;d remote administration (default is off) and use the <link linkend="chapter-refdbd"><command moreinfo="none">kill</command> command</link> or the <link linkend="sect2-starting-refdbd-script">refdbctl</link> script instead.</para> - </listitem> - <listitem> - <para>Most of the &appname;a commands require database administrator rights. </para> - </listitem> - </itemizedlist> - <sect3> - <title>MySQL</title> - <para>If you run MySQL as your database server, these things apply as well:</para> - <itemizedlist> - <listitem> - <para>When adding users with the <link linkend="app-admin-command-adduser"><command moreinfo="none">adduser</command></link> command the <option>-H</option> option has to specify the box where &appname;d runs as the host, not the box from where the user will run the clients. If you do not specify a host, "localhost" is assumed.</para> - </listitem> - <listitem> - <para>To allow remote connections to the database server, the MySQL configuration file <filename moreinfo="none">my.cnf</filename> must not contain the option "skip-networking", and the start script must not use the command-line option <option>--skip-networking</option>. Many operating systems use one of these methods in default installations to restrict access to local users for security reasons.</para> - </listitem> - <listitem> - <para>If you install and run MySQL yourself, you should not use the default database administrator account. The name (root) is widely known and by default this account is not password-protected. To make your database server secure, please create a new database administrator account with a different name and specify a password.</para> - </listitem> - </itemizedlist> - </sect3> - <sect3> - <title>PostgreSQL</title> - <para>If you run PostgreSQL as your database server, these hints are for you:</para> - <itemizedlist> - <listitem> - <para>The host-based part of the PostgreSQL access control is not accessible through the SQL interface. Therefore, the &appname;a command <link linkend="app-admin-command-adduser"><command>adduser</command></link> cannot provide the host information (in other words, the <option>-H</option> is ignored).</para> - <para>Instead, the host-based part of the access control is specified in the PostgreSQL configuration file, usually <filename moreinfo="none">/home/pgsql/data/pg_hba.conf</filename>. On most operating systems, the default configuration allows unrestricted access for all users on the local system, but no remote access. Use something like the following entries to enforce usage of passwords for both local access and remote access from the network 192.168.1.0 to &appname; and a reference database "refs":</para> - <programlisting format="linespecific"> -# host DBNAME IP_ADDRESS ADDRESS_MASK AUTH_TYPE [AUTH_ARGUMENT] - local &appname; crypt - local refs crypt - - host &appname; 192.168.1.0 255.255.255.0 crypt - host refs 192.168.1.0 255.255.255.0 crypt - </programlisting> - <para>As mentioned previously, only the host where &appname;d runs is relevant for the host or network entries in the configuration file.</para> - <para>Make sure to read the PostgreSQL documentation to get your access control right.</para> - <note> - <para>Please keep in mind that <filename>postmaster</filename> (the PostgreSQL database server parent process) needs to be started with the <option>-i</option> option to accept remote connections at all. Most default installations do not use this switch to increase security.</para> - </note> - </listitem> - <listitem> - <para>If you install and run PostgreSQL yourself, you should not use the default database administrator account. The name (pgsql) is widely known and by default this account is not password-protected. To make your database server secure, please create a new database administrator account with a different name and specify a password.</para> - </listitem> - </itemizedlist> - </sect3> - </sect2> - <sect2> - <title>Web access</title> - <para>Web access adds some security flaws to your system. Usernames and passwords will travel happily as plaintext between the browser and the web server. If you choose to store the access information as a cookie to simplify subsequent accesses, the username and password will be stored on the disk as plain text. It may be prudent to create special database accounts with restricted access rights for use with the web interface.</para> - </sect2> - </sect1> - <sect1> - <title>How to run several &appname; instances</title> - <para>In all but a few cases, having one &appname;d daemon per network is absolutely sufficient. However, there are a few cases where you may end up running more than one instance of &appname;d on the same computer at the same time:</para> - <itemizedlist> - <listitem> - <para>You want to provide access to more than one database engine. The only good reason to do this may be to test-drive a different database engine.</para> - </listitem> - <listitem> - <para>You want to test-drive a new &appname; release without interrupting the access to your installed version</para> - </listitem> - <listitem> - <para>You do not want to run &appname;d as a daemon serving all users. Instead, each user should be able to run his own copy of &appname;d</para> - </listitem> - </itemizedlist> - <para>You'll have to configure each &appname;d process individually. If each user starts his own copy of the application server, private <filename moreinfo="none">.refdbdrc</filename> configuration files in the users' <envar>$HOME</envar> directory allow a simple setup. If you want to run more than one daemon as non-user-processes, you cannot safely use the <command>refdbctl</command> script to control the instances. Instead you should start and stop the daemons manually and use the appropriate command-line options to configure each process individually. The options which need to be set differently whenever more than one &appname;d instance runs on the same box are:</para> - <itemizedlist> - <listitem> - <para><option>-D</option>, <option>-i</option>, and<option>-b</option> to set the database engine, IP address, and the port it listens on, respectively. Only required if you fiddle with two different database engines.</para> - </listitem> - <listitem> - <para><option>-e</option> and <parameter moreinfo="none">-L</parameter> to use separate log files for the two instances. This may be easier to evaluate than using syslog, although the processes can be distinguished by means of their process ID.</para> - </listitem> - <listitem> - <para><option>-P</option> to use separate PID files</para> - </listitem> - <listitem> - <para><option>-p</option> to set the port each &appname;d instance listens on. The ports must be different, otherwise clients can't select which instance to connect to.</para> - </listitem> - </itemizedlist> - <para>On the client side you'll need only set the <varname>port</varname> configuration variable or use the <option>-p</option> command line option to select the application server instance that you want to connect to.</para> - </sect1> </chapter> Index: refdb-manual-chapter8.sgml =================================================================== RCS file: /cvsroot/refdb/refdb/doc/refdb-manual-chapter8.sgml,v retrieving revision 1.13.2.1 retrieving revision 1.13.2.2 diff -u -U2 -r1.13.2.1 -r1.13.2.2 --- refdb-manual-chapter8.sgml 14 Nov 2004 16:04:50 -0000 1.13.2.1 +++ refdb-manual-chapter8.sgml 25 Nov 2004 21:28:42 -0000 1.13.2.2 @@ -116,4 +116,322 @@ <para>Use the &appname;a command <link linkend="app-a-command-deletestyle"><command moreinfo="none">deletestyle</command></link> to remove one or more bibliography styles from the database. The argument for this command is a Unix regular expression. All styles whose name match the regular expression will be deleted.</para> </sect1> + <sect1> + <title>Setting up the &appname; web services</title> + <para>This section guides you through the necessary steps to run &appname;c, bib2ris, and med2ris.pl as <acronym>CGI</acronym> applications. This will allow the users to enjoy a part of the functionality of &appname; through a web interface.</para> + <para>If you want to work through this section you'll need some basic knowledge about the administration of your web server. Needless to say that you also need the proper privileges to fiddle with your web server settings. The procedure below was written with <ulink url="http://www.apache.org">Apache</ulink> 1.3 on Debian GNU/Linux in mind. Apache is by far the most popular web server and available on various platforms, including all platforms that &appname; currently supports. If you use a different Linux distribution or a different operating system, the location and name of the files may slightly differ. If you use a different web server, the configuration process may be entirely different, but with the user manual at your hands you may be able to adapt the following instructions to your needs.</para> + <note> + <para>If your web server and the &appname;d application server run on different machines, please notice that all but one steps below talk about the computer running the web server. One step talks about the computer running &appname;d.</para> + </note> + <procedure> + <step performance="required"> + <para>To tell Apache about the &appname; web pages, add the following line to <filename>/etc/apache/httpd.conf</filename>:</para> + <programlisting format="linespecific"> +Alias /refdb/ /usr/local/share/refdb/www/ +</programlisting> + <para>This entry will let you access the &appname; web interface through the address [hostname]/refdb. While you're at modifying <filename moreinfo="none">httpd.conf</filename>, the next step may require another change to this file.</para> + </step> + <step performance="required"> + <para>Most web servers expect CGI applications in one specific, configurable directory. If your web server is not already set up for CGI applications, you`ll have to register a cgi-bin directory. To do this in the case of Apache, add the following line to <filename>/etc/apache/httpd.conf</filename>:</para> + <programlisting> +ScriptAlias /cgi-bin/ /usr/local/bin/apache/cgi-bin/ +</programlisting> + <para>You can of course choose a different directory if you wish.</para> + <para>The directory must be readable and accessible for the account that the web server daemon runs in (this is often user "www" and group "www", which I will use in the example below). If this is not already the case, issue something like the following commands:</para> + <screen format="linespecific"><prompt moreinfo="none">#~ </prompt><userinput moreinfo="none">chown www:www /usr/local/bin/apache/cgi-bin</userinput></screen> + <screen><prompt>#~ </prompt><userinput>chmod u+rx /usr/local/bin/apache/cgi-bin</userinput></screen> + <para>Now you have to tell Apache about the updated configuration:</para> + <screen><prompt>#~ </prompt><userinput>apachectl restart</userinput></screen> + </step> + <step performance="required"> + <para>Place copies of <filename>&appname;c</filename>, <filename>bib2ris</filename>, and <filename>med2ris.pl</filename> in your <filename class="directory">/cgi-bin</filename> directory. Unless they are readable and executable for everyone you'll have to make them read/executable for the web server daemon:</para> + <screen format="linespecific"><prompt moreinfo="none">#~ </prompt><userinput moreinfo="none">cd /usr/local/bin/apache/cgi-bin/</userinput></screen> + <screen format="linespecific"><prompt moreinfo="none">#~ </prompt><userinput moreinfo="none">chown www:www &appname;c bib2ris med2ris.pl</userinput></screen> + <screen><prompt>#~ </prompt><userinput>chmod u+rx &appname;c bib2ris med2ris.pl</userinput></screen> + </step> + <step performance="required"> + <para>Create the <link linkend="sect1-mystery-init-files">configuration files</link> <filename>/usr/local/etc/&appname;/&appname;cgirc</filename>, <filename>/usr/local/etc/&appname;/bib2riscgirc</filename>, and <filename>/usr/local/etc/&appname;/med2riscgirc</filename> (unless you chose a different directory during configuration) and fill in appropriate values. Remember that bib2ris and med2ris need access to HTML templates. You should specify the proper value for &appname;lib in the configuration files.</para> + </step> + <step> + <para>You can of course <link linkend="ch-customize-web">modify the HTML files and the stylesheet</link> according to your needs. The static HTML files, a CSS stylesheet file, and a JavaScript file are installed by default in <filename class="directory">/usr/local/share/refdb/www</filename>, whereas the HTML templates are installed in <filename class="directory">/usr/local/share/refdb/templates</filename> <emphasis>on the computer that runs &appname;d</emphasis>. Both the computer that runs Apache and the CGI programs and the computer that runs &appname;d need a copy of <filename class="directory">/usr/local/share/refdb/templates</filename>.</para> + </step> + <step> + <para>The file <filename>refdbquery.html</filename> is the main entry point to the &appname; web interface. Web visitors should be guided to this page as it allows username/password authentication. The &appname; installation procedure creates a symlink with the name <filename moreinfo="none">index.html</filename> pointing to <filename>refdbquery.html</filename>, so you'll be able to access the main query page by pointing your browser to "[hostname]/refdb/".Provide links on your web pages accordingly.</para> + </step> + </procedure> + <para>It may be a good idea to check the access rights of all related files again to make sure the site visitors can access them from their browser. The static HTML pages, the templates, the javascript file, and the CSS style sheet must be readable for the account the web server is started under. The templates must be readable for the account &appname;d is started under.</para> + </sect1> + <sect1> + <title>Logging data</title> + <para>The &appname; programs can spill out quite a lot of log messages to keep track of what is happening in your programs. This section explains the basics of setting up your message logging.</para> + <sect2> + <title>What to log</title> + <para>The application server &appname;d as well as all command-line clients can generate log messages. Message logging is most important for two purposes:</para> + <itemizedlist> + <listitem> + <para>Keep track of non-interactive programs. This includes &appname;d as well as &appname;c, bib2ris, and nmed2ris if they are run as CGI applications. It may include all clients if they are run from scripts.</para> + </listitem> + <listitem> + <para>Track down bugs or user errors.</para> + </listitem> + </itemizedlist> + <para>A useful approach is to log all messages with a log level (explained <link linkend="sect2-log-level">below</link>) of 6. This would give you a good overview over the usage of these programs but would not clutter the log files with debug information. Switch to log level 7 only if you suspect a bug or some user error and need the full debug information to understand the problem.</para> + <para>For the interactive use of the clients logging is usually not necessary, so you'd use a log level of -1 to prevent logging altogether or a log level of maybe 3 or 4. In the latter case you'd get log messages only if something goes badly wrong. Again, if you encounter bugs or user errors you may switch on debug messages by using a log level of 7.</para> + </sect2> + <sect2> + <title>Destinations</title> + <para>There are three possible destinations the log messages can be sent to. Select the proper destination with either the <varname>logdest</varname> variable in the configuration file or the <option>-e</option> switch on the command line. In both cases the values in the following list are accepted. You may use either the numerical value or the case-insensitive string in brackets, e.g. <option>-e 1</option> and <option>-e syslog</option> are equivalent.</para> + <variablelist> + <varlistentry> + <term>0 (stderr)</term> + <listitem> + <para>stderr is mostly useful for debugging purposes when &appname;d is run as a standalone process and when clients are run interactively. stderr does not make much sense if you run &appname;d as a daemon (daemons detach from the console at startup, so all output to stderr is lost).</para> + </listitem> + </varlistentry> + <varlistentry> + <term>1 (syslog)</term> + <listitem> + <para>Sending the data to syslog integrates the log data with the rest of your system's log output. The log messages will be sent to the user facility, which usually is configured to write to <filename>/var/log/user.log</filename>. See the syslog(8) man page for information how to configure the syslog facility.</para> + <note> + <para>If you run &appname;d on Cygwin, the syslog messages are sent to the application message list in the NT message logging system. If you are used to going through your log output with tools like grep and awk, you may find it more useful to write to a custom log file instead.</para> + </note> + </listitem> + </varlistentry> + <varlistentry> + <term>2 (file)</term> + <listitem> + <para>You can define the full path of a custom log file with either the <varname>logfile</varname> configuration file parameter or the <option>-L</option> command line option. By default, &appname; applications write their log output to <filename>/var/log/<appname>.log</filename>. Make sure to set the appropriate access rights for these log files.</para> + </listitem> + </varlistentry> + </variablelist> + <note> + <para>Some libraries used by &appname;, e.g. the PostgreSQL client library, send log messages to stderr. This is not controlled by the log settings of &appname;d. The same PostgreSQL log messages show up in the PostgreSQL log which is usually sent to <filename moreinfo="none">/var/log/pgsql</filename>.</para> + </note> + </sect2> + <sect2 id="sect2-log-level"> + <title>Log levels</title> + <para>You can select how verbose the log output of &appname;d will be. You can do this by either setting the <varname>loglevel</varname> configuration file variable or the <option>-l</option> command line option to an appropriate value. You may either use the numerical value or the case-insensitive string as explained in the table below. E.g. <option>-l 5</option> and <option>-l notice</option> are equivalent. Set the log level to -1 to disable logging completely. Use a value from 0 through 7 to generate increasingly verbose log output. The definitions of the log levels are taken from the include file <filename>syslog.h</filename>:</para> + <table id="table-loglevel-definitions"> + <title>Log level definitions</title> + <tgroup cols="3"> + <thead> + <row> + <entry>level</entry> + <entry>verbose</entry> + <entry>explanation</entry> + </row> + </thead> + <tbody> + <row> + <entry>0</entry> + <entry>emerg</entry> + <entry>system is unusable</entry> + </row> + <row> + <entry>1</entry> + <entry>alert</entry> + <entry>action must be taken immediately</entry> + </row> + <row> + <entry>2</entry> + <entry>crit</entry> + <entry>the system is in a critical condition</entry> + </row> + <row> + <entry>3</entry> + <entry>err</entry> + <entry>there is an error condition</entry> + </row> + <row> + <entry>4</entry> + <entry>warning</entry> + <entry>there is a warning condition</entry> + </row> + <row> + <entry>5</entry> + <entry>notice</entry> + <entry>a normal but significant condition</entry> + </row> + <row> + <entry>6</entry> + <entry>info</entry> + <entry>a purely informational message</entry> + </row> + <row> + <entry>7</entry> + <entry>debug</entry> + <entry>messages generated to debug the application</entry> + </row> + </tbody> + </tgroup> + </table> + <para>Setting the log level to a given value means that all messages with a priority level up to the given value will be logged. E.g. if you set the log level to 6 (which is a reasonable default value), all messages with a priority from 0 through 6 will be logged, whereas messages with a priority level of 7 will be ignored.</para> + <warning> + <para>Use log level 7 with caution. The amount of log messages is considerable and sufficient to slow down the application. You should not use this level in everyday use, only to track down bugs or user errors that you may encounter.</para> + </warning> + </sect2> + <sect2> + <title>Interpreting the log information</title> + <para>If the messages are sent to stderr, only the message proper will be printed. If the messages are sent to the syslog facility, the default format including the process name and process ID is used.</para> + <para>A line in the custom log file looks like this:</para> + <programlisting>6:pid=267:Sun Jul 22 18:39:52 2001:application server started</programlisting> + <para>You will easily recognize the following fields:</para> + <programlisting>message_priority:process_id:time:message</programlisting> + <variablelist> + <varlistentry> + <term>message priority</term> + <listitem> + <para>This is the priority assigned to the message by &appname;d. The values are explained <link linkend="table-loglevel-definitions">above</link>.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>process ID</term> + <listitem> + <para>This is the process ID (as seen in the <command>ps ax</command> listing) of the &appname; process that generated the message. In the case of &appname;d this may either be the parent process (the one that generated the above "application server started" message) or one of the children that are forked off to answer client requests.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>time</term> + <listitem> + <para>This is the full time and date information when the message was generated.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>message</term> + <listitem> + <para>This is the message text proper.</para> + </listitem> + </varlistentry> + </variablelist> + <para>The message entries are sufficiently structured to allow easy access to the information with the standard Unix tools like <application>awk</application> and <application>grep</application>.</para> + </sect2> + </sect1> + <sect1> + <title>Security issues</title> + <para>This section briefly discusses some security-related issues that you might want to think about as an administrator. We'll look at the access control provided by the external database servers MySQL and PostgreSQL.</para> + <note> + <para>The embedded database engine SQLite does not provide built-in access control. All you can do is use <command moreinfo="none">chown</command> and <command moreinfo="none">chmod</command> to restrict access to the database files. There is no way to restrict access through &appname;.</para> + </note> + <sect2> + <title>Passwords</title> + <para>&appname; tries to support the security features of the SQL database servers as far as possible. This includes the username/password-based access rights scheme (not much surprise here). Since version 0.6.0 the passwords are no longer transmitted as plain text between the clients and the server. This means that it now makes sense to keep the passwords secret. There are several ways to specify the password when starting a &appname; client. These ways differ with respect to the security of the passwords and are listed here in the order of <emphasis>increasing</emphasis> security:</para> + <variablelist> + <varlistentry> + <term>Specify the password on the command line</term> + <listitem> + <para>The password is stored nowhere on the filesystem and thus pretty secure from this point of view. But the full command line can be viewed with the <command moreinfo="none">ps</command> command by any user on the system, so the unencrypted password is basically world-readable at least for a very brief period until the applications have a chance to hide the string.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>Store the password in the personal configuration file</term> + <listitem> + <para>This way the password is protected from other users who habitually run the <command moreinfo="none">ps</command> command just for the heck of it. But now it is stored unencrypted on the hard drive, and you must make sure that no one else can read the configuration file (no group or world read access).</para> + </listitem> + </varlistentry> + <varlistentry> + <term>Specify the password interactively</term> + <listitem> + <para>This is the default behaviour if the password is not specified either in the configuration file or on the command line. The &appname; client will ask for the password. This is certainly the most secure way to provide a password, but this won't work if you run the clients unattended via scripts.</para> + </listitem> + </varlistentry> + </variablelist> + </sect2> + <sect2 id="sect-database-server-access-control"> + <title>Database server access control</title> + <para>It is beyond the scope of this manual to reiterate the security models of the database servers, but you need to keep in mind a few aspects relevant to &appname;.</para> + <itemizedlist> + <listitem> + <para>One component of the database server access control is based on the host from which you connect to the database server. This is partially circumvented by the &appname; three-tier design. Keep in mind that only &appname;d communicates with the database server. Therefore only the host where &appname;d runs is relevant for the access control. There is currently no system in place for checking whether a client is allowed to connect to the &appname;d application server from a particular host.</para> + </listitem> + <listitem> + <para>Both MySQL and PostgreSQL distinguish between local and remote connections. Access needs to be granted separately if you want to use both local and remote connections</para> + <note> + <para>On many operating systems the default installations of MySQL and PostreSQL do not allow remote connections for security reasons. You need to manually allow remote connections as described below.</para> + </note> + </listitem> + <listitem> + <para>The &appname;a commands to remotely reconfigure a running application server are currently protected by a simple table access test. In any serious database server installation, only the database administators have read access to certain system tables. The current implementation of this check requires that you have access to this table if you want to run the <link linkend="app-admin-command-confserv"><command moreinfo="none">confserv</command></link> commands. You should be aware that if the access rights are set up improperly, you may also allow everyone and their grandma to stop or reconfigure the &appname;d application server. If you cannot restrict read access to system tables for whatever reason, you should not enable &appname;d remote administration (d... [truncated message content] |
