Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
ezmlm-cgi(1)		    General Commands Manual		  ezmlm-cgi(1)

NAME
       ezmlm-cgi - provide WWW access to the list archive

SYNOPSIS
       ezmlm-cgi

DESCRIPTION
       ezmlm-cgi  is  executed by the httpd daemon and generates HTTP/CGI/html
       4.0-compliant self-referencing output of	index pages for	threads	 in  a
       given month, messages in	a thread, messages by a	given author, messages
       by date,	and messages themselves	with full navigation controls. It uses
       the archive directly, aided by index files created by ezmlm-idx(1), and
       ezmlm-send(1) as	part of	normal archive access and digest indexing, and
       by ezmlm-archive(1).

       ezmlm-cgi  uses	the  httpd-supplied  variables PATH_INFO to obtain the
       list  number,  QUERY_STRING  to	obtain	the  command,	as   well   as
       SERVER_NAME,  SERVER_PORT, and SCRIPT_NAME to create a self-referencing
       URL.

       When ezmlm-cgi is invoked without a command, it shows the  threads  for
       the  current month.  If no list number is supplied, the default list is
       shown (see below).

CONFIGURATION
       ezmlm-cgi expects to find configuration info in /etc/ezmlm/ezcgirc when
       run SUID	root, or .ezcgirc otherwise. The entries in this file describe
       one list	per line. Blank	lines and comments starting with  a  ``#''  in
       position	 1 are allowed and ignored. No extra blanks, tab, etc, are al-
       lowed. Entries must be of the following format:

       listno;uid;listdir;listaddr;buttonbar;charset;style;bannerprog

       where:

       listno
	    is the list	number using ``0'' for the default list	if desired;

       uid  the	user id	to switch to if	installed SUID root (default  invoking
	    user  id) and if preceded by ``-'' chroot()	is suppressed for SUID
	    root installations;

       listdir
	     the absolute path to the list base	directory (required);

       listaddr
	    the	list address as	local@host (required) and if preceded by ``-''
	    the	 ``From:'' E-mail address is replaced by the posters name/han-
	    dle	as a further precaution	against	address	harvesting;

       buttonbar
	    a set of comma-separated fields of the type	 ``[Home]=http://exam-
	    ple.com/list.html''.   The text before the ``='' is	the exact text
	    displayed and the subsequent text should be	the URL	linked to that
	    button. Use	the braces to make the buttons be consistent with pre-
	    existing navigation	buttons. It is desirable to add	 a  ``[Help]''
	    button  with a link	to an explanation of the various displays gen-
	    erated by ezmlm-cgi.

       charset
	    the	  character   set   used   for	 the   main   pages   (default
	    ``iso-8859-1'');

       style
	    the	style sheet used (default none,	which doesn't look pretty);

       bannerprog
	    the	path to	a banner program which is given	the name of the	script
	    and	the list as arguments (default none). The path is relative  to
	    ``listdir''	 and  can  point anywhere in the file system. However,
	    for	SUID root installations	access is normally restricted via  ch-
	    root(3).   (See  SECURITY.)	 If ``bannerprog'' starts with a less-
	    than character (''<'') it is assumed to be a URL which is inserted
	    as is, rather than executed.

       ``;''
	    the	 separator can be any non-numeric character and	can be differ-
	    ent	for different ezcgirc  lines.  There  is  no  quoting/escaping
	    mechanism.	Thus, choose a character not present in	any of the ar-
	    guments. ``bannerprog'' as the last	argument is an exception,  and
	    may	contain	any characters except LF and NUL.

OPTIONS
       If ``uid'' is preceded by a minus sign (``-''),
	    ezmlm-cgi  will  not  call chroot(3) .  This potentially decreases
	    security, but may be needed	to execute ``bannerprog''.

       If ``listaddr'' is preceded by a	minus sign (``-''),
	    ezmlm-cgi will, as a precaution against address harvesting robots,
	    remove  the	sender's E-mail	address	also in	the message view. This
	    is already done in all other views.	The archive user can still ob-
	    tain the address by	requesting the message by E-mail.

OUTPUT
       ezmlm-cgi outputs 5 different views.

       thread index
	      shows the	threads	which have messages in a given month. The sub-
	      ject is prefixed with the	number of messages in the  thread  for
	      the  given  month. When ezmlm-archive(1) is first	run against an
	      existing archive,	the number is the total	number of messages  in
	      the  thread.  The	subject	and author are links to	the respective
	      thread or	author index. The threads are ordered in reverse order
	      of  latest message, i.e. the thread that last received a message
	      is listed	last. When ezmlm-archive(1) is run against an existing
	      archive,	the  initial  sort is in order of the first message in
	      the thread.

	      The subject in the thread	index is a link	to the last message in
	      the thread.

       thread shows  the  messages in the respective thread in date order. For
	      each message the author is shown linked to the message.

       author index
	      shows the	subject	of all messages	posted from a given address in
	      order of arrival at the list. Links are to the messages.

       message by date
	      shows entries in order of	arrival	of sets	of 100 messages. Links
	      are to the message and to	the author.

       message
	      shows the	message	itself.	The message has	links to the  previous
	      and  next	message	by time, in the	thread,	or by the same author.
	      There are	also links to the other	views, as  well	 as  links  to
	      subscribe,  or request FAQ, the message or the thread by E-mail.
	      The navigation bar is very concise  to  optimize	appearance  in
	      lynx.   It  is  self-explanatory to anyone daring	to experiment.
	      For others, you may wish to supply a ``help'' button.  The  mes-
	      sage subject is a	mailto:	link for a follow-up post to the list.

OUTPUT FORMATTING
       ezmlm-cgi  outputs  html	 4.0  in  a format suitable for	Lynx and other
       text-mode browsers. The format is designed for easy  optional  enhance-
       ment  via  CSS1/2 type style sheets in the format ``text/css''.	ezmlm-
       cgi is self-documenting in this respect.	Simply review  the  output  in
       the  different views and	the sample style sheet to see the class	struc-
       ture.

EXTERNAL LINKS TO MESSAGES
       ezmlm-cgi will accept a PATH_INFO of the	following format:

       /listno/message

       where:

       listno
	    is the list	number per config file;

       message
	    is the message number.

	    Thus, ezmlm-cgi/2/20000 will return	message	20000 from list	2.

	    ezmlm-cgi uses a second syntax based on QUERY_STRING for  internal
	    links. This	command	set is implemented only	as far as required for
	    normal ezmlm-cgi function. Useful are:

       ezmlm-cgi?listno?ams:message
	    which will return in order the list	of messages posted by the  au-
	    thor of message message on list listno, and

       ezmlm-cgi?listno?sms:message
	    which will return in order the list	of messages with the same sub-
	    ject as message message on list listno, i.e. the ``thread''.

ROBOTS
       There are many possible URLs for	the same message.  To still allow  ex-
       ternal  indexing,  ezmlm-cgi supports the command ezmlm-cgi/index which
       returns a page with links to all	lists, except the default list.	 These
       links  indirectly lead exactly once to each message.  None of the links
       used contain a ``?''. Thus, to index  the  archives,  allow  access  to
       scripts	in  the	(separate) directory where ezmlm-cgi is	installed, but
       deny access to directory/ezmlm-cgi?.  Any message will have a  ``nofol-
       low''  robot  META  tag,	 and  any  view	 reached  by  a	 URL  based on
       QUERY_STRING will in addition have a  ``noindex''  robot	 META  tag  to
       avoid trapping robots in	the archive.

EXECUTION
       ezmlm-cgi  can  operate	in two modes, SUID root	and normal.  ezmlm-cgi
       should not be installed SUID user other than root.  Please see the  SE-
       CURITY section before installing	SUID root.

       In  normal  mode,  ezmlm-cgi  will read the configuration file .ezcgirc
       from the	working	directory set by the httpd daemon (per cgi  definition
       this  should be the same	directory as ezmlm-cgi is in), then change di-
       rectory to the list directory. ``uid'' is ignored.  For user  installa-
       tions or	systems	where the httpd	user has access	to all the lists, nor-
       mal mode	usually	gives sufficient access.

       In SUID root mode, ezmlm-cgi will  read	the  configuration  info  from
       /etc/ezmlm/ezcgirc then change directory	to that	directory, then	change
       root to that directory, then change userid to ``uid''.  If  ``uid''  is
       not specified, it will change to	the uid	of the process invoking	ezmlm-
       cgi (normally the httpd user). If the archive files are world-readable,
       but the list directory is not, it is safest to leave ``uid'' blank. The
       httpd user will still be	able to	read the files.

EXECUTION OF BANNER PROGRAMS
       ezmlm-cgi supports display of banners, but not execution	of banner pro-
       grams.  To  obtain  dynamic  banners, use a URL that points to a	banner
       program elsewhere.

SECURITY
       ezmlm-cgi will refuse to	run as root.

       ezmlm-cgi does not write	or lock	any files.

       ezmlm-cgi has a short well commented segment of code  that  potentially
       runs  SUID  root.   Read	 the  source to	convince yourself that this is
       safe. If	possible, install it SUID user,	or not SUID at	all,  if  that
       meets  your  needs (single list user, httpd user	is list	user, or httpd
       user has	sufficient access to all list directories and archives).

       ezmlm-cgi will not allow	execution of banner programs.

BUGS
       ezmlm-send(1) updates the list message counter once a message is	safely
       archived,  but before it	is accepted by qmail(7).  Also,	the index file
       is updated before the message is	accepted  by  qmail(7).	  If  qmail(7)
       fails,  ezmlm-send(1) resets the	counter	before terminating. It is pos-
       sible that in such a situation the message would	be replaced by a  dif-
       ferent  one.  If	ezmlm-cgi accesses a message that ultimately fails and
       in that time interval, it may expose a message that ultimately  is  re-
       placed,	especially  when  doing	 it  via the ``Messages	by date'' view
       which is	based on the index file. In practice, this is relatively harm-
       less.  Avoiding	it would require locking the list with significant im-
       plications for security and performance.

SEE ALSO
       ezmlm-archive(1), ezmlm-get(1), ezmlm-idx(1), ezmlm-send(1),  ezmlm(5),
       qmail(7)

								  ezmlm-cgi(1)

NAME | SYNOPSIS | DESCRIPTION | CONFIGURATION | OPTIONS | OUTPUT | OUTPUT FORMATTING | EXTERNAL LINKS TO MESSAGES | ROBOTS | EXECUTION | EXECUTION OF BANNER PROGRAMS | SECURITY | BUGS | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=ezmlm-cgi&sektion=1&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help