sympa.tex 186 KB
Newer Older
root's avatar
root committed
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
%
% Copyright (C) 1999, Institut Pasteur & Christophe Wolfhugel
% Copyright (C) 1999, Comité Réseau des Universités & Serge Aumont, Olivier Salaün
% Copyright (C) 1999, UVSQ & Pierre David
% 
%
% Historique
%   1999/04/12 : pda@prism.uvsq.fr : conversion to latex2e
%


\documentclass [twoside,a4paper] {report}

    \usepackage {epsfig}
    \usepackage {xspace}
    \usepackage {makeidx}
    \usepackage {html}

    \usepackage {palatino}
    \renewcommand {\ttdefault} {cmtt}

    \setlength {\parskip} {5mm}
    \setlength {\parindent} {0mm}

    \pagestyle {headings}
    \makeindex

    \sloppy

    \usepackage [dvips] {changebar}
    % \begin {changebar} ... \end {changebar}
    % ou \cbstart ... \cbend   et \cbdelete

    %
    % Change bars are not well rendered by latex2html
    %

    \begin {htmlonly}
        \renewcommand {\cbstart} {}
        \renewcommand {\cbend} {}
        \renewcommand {\cbdelete} {}
    \end {htmlonly}

    % black text on a white background, links unread in red
    % \bodytext {TEXT="#000000" BGCOLOR="#ffffff" LINK="#ff0000"}
    % black text on a white background
    \bodytext {TEXT="#000000" BGCOLOR="#ffffff"}

    \newcommand {\fig} [2]
    {
        \begin {figure} [htbp]
            \hrule
            \vspace {3mm}
            \begin {center}
                \epsfig {figure=#1.ps}
%                \epsffile {figure=#1.ps}
            \end {center}
            \vspace {2mm}
            \caption {#2}
            \vspace {3mm}
            \hrule
            \label {fig:#1}
        \end {figure}
    }

    \newcommand {\version} {2.7}

    \newcommand {\samplelist} {mylist}

    % #1 = text to index and to display
    \newcommand {\textindex} [1] {\index{#1}#1}

    % #1 = sort key, #2 displayed in text and index
    \newcommand {\textindexbis} [2] {\index{#1@#2}#2}

    \newcommand {\Sympa} {\textit {Sympa}\xspace}

    \newcommand {\WWSympa} {\textindexbis {WWSympa}{\textit {WWSympa}}\xspace}

    % #1 = sort key, #2 : displayed in text and index, #3 displayed in index
    \newcommand {\ttindex} [3]  {\index{#1@\texttt {#2} #3}\texttt {#2}}

    \newcommand {\example} [1] {Example: \texttt {#1}}

85
    \newcommand {\unixcmd} [1] {\ttindex {#1} {#1} {UNIX command}}
root's avatar
root committed
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151

    \newcommand {\mailcmd} [1] {\ttindex {#1} {#1} {mail command}}

    \newcommand {\cfkeyword} [1] {\ttindex {#1} {#1} {configuration keyword}}

    \newcommand {\default} [1]  {(Default value: \texttt {#1})}

    \newcommand {\scenarized} [1] {\texttt {#1} parameter is defined by scenario (see~\ref {scenarii}, page~\pageref {scenarii})}

    \newcommand {\lparam} [1] {\ttindex {#1} {#1} {list parameter}}

    \newcommand {\file} [1] {\ttindex {#1} {#1} {file}}

    \newcommand {\dir} [1]  {\ttindex {#1} {#1} {directory}}

    \newcommand {\tildefile} [1] {\ttindex {#1} {\~{}#1} {file}}

    \newcommand {\tildedir} [1] {\ttindex {#1} {\~{}#1} {directory}}

    \newcommand {\rfcheader} [1] {\ttindex {#1:} {#1:} {header}}

    % Notice: use {\at} when using \mailaddr
    \newcommand {\at} {\char64}
    \newcommand {\mailaddr} [1] {\texttt {#1}}   
% mail address
%        {\ttindex {#1} {#1} {mail address}}


\begin {document}

    \title {\Huge\bf Sympa \\ \huge\bf Mailing Lists Management Software}
    \author {
        Serge Aumont,
        Olivier Sala\"un,
        Christophe Wolfhugel,
         }
    \date {September 2000}
\begin {htmlonly}
For printing purpose, use the 
\htmladdnormallink {postscript format version} {sympa.ps} of this documentation.
\end {htmlonly}

\maketitle


{
    \setlength {\parskip} {0cm}



    \cleardoublepage

    \tableofcontents
    % \listoffigures
    % \listoftables
}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Presentation
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\cleardoublepage
\chapter {Presentation}

\Sympa is an electronic mailing list manager.  It is used to automate
list management functions such as subscription, moderation,
152
archive and shared document management. 
root's avatar
root committed
153
It also includes management functions which
154
155
would normally require a substantial amount of work (time-consuming
and costly for the list owner). These
root's avatar
root committed
156
functions include automatic management of subscription renewals,
157
158
159
160
161
162
163
164
list maintenance, and many others.

\Sympa manages many different kinds of lists. It includes
a web interface for all list functions including management. It allows
a precise definition of each list feature, such as sender authorization,
the moderating process, etc. \Sympa defines, for each feature of each list,
exactly who is authorized to perform the relevant operations, along with the
authentication method to be used. Currently, authentication can be based
165
on either an SMTP From header, a password, or an S/MIME signature.\\
166
167
\Sympa is also able to extract electronic
addresses from an LDAP directory or SQL server, and include them
root's avatar
root committed
168
169
dynamically in a list.

170
171
172
173
\Sympa manages the dispatching of messages, and makes it possible to
reduce the load on the computer system where it is installed. In
configurations with sufficient memory, \Sympa is especially well
adapted to handling large lists: for a list of 20,000 subscribers, it requires
root's avatar
root committed
174
175
less than 6 minutes to send a message to 95 percent of the subscribers,
assuming that the network is available (tested on a 300~MHz, 256~MB
176
i386 server with Linux).
root's avatar
root committed
177

178
This guide covers the installation, configuration and management of
root's avatar
root committed
179
180
181
182
183
the current release (\version) of
\htmladdnormallink {sympa} {http://listes.cru.fr/sympa/}.

\section {License}

184
\Sympa is free software; you may distribute it under the terms
root's avatar
root committed
185
186
187
188
189
190
191
192
193
194
of the
\htmladdnormallinkfoot {GNU General Public License Version 2}
        {http://www.gnu.org/copyleft/gpl.html}

You may make and give away verbatim copies of the source form of
this package without restriction, provided that you duplicate all
of the original copyright notices and associated disclaimers.

\section {Features}

195
196
197
198
\Sympa provides all the basic features that any mailing list management robot
should include. While most \Sympa features have their equivalents in other
mailing list applications, \Sympa is unique in including features
in a single software package, including:
root's avatar
root committed
199
200

\begin {itemize}
201
    \item High speed distribution processing and load control. \Sympa
root's avatar
root committed
202
        can be tuned to allow the system administrator to control
203
204
        the amount of computer resources used.  Its optimized algorithm
        allows:
root's avatar
root committed
205
206

        \begin {itemize}
207
            \item the use of your preferred SMTP engine, e.g.
root's avatar
root committed
208
                \unixcmd {sendmail}, \unixcmd {qmail} or \unixcmd
209
                {postfix}
root's avatar
root committed
210

211
            \item tuning of the maximum number of SMTP child processes
root's avatar
root committed
212

213
214
            \item grouping of messages according to recipients' domains,
	    	and tuning of the grouping factor
root's avatar
root committed
215

216
            \item detailed logging
root's avatar
root committed
217
218
219

        \end {itemize}

220
    \item \textbf {Multilingual} messages. The current version of
root's avatar
root committed
221
        \Sympa allows the administrator to choose the language
222
223
224
225
226
227
228
229
        catalog at run time. At the present time the \Sympa robot is available in
        English, Spanish, French, German, Italian, Polish, Finnish and Chinese
	(Big5 and GB). The web interface is available in English, Spanish
	and French.

    \item \textbf {MIME support}. \Sympa naturally respects
        \textindex {MIME} in the distribution process, and in addition
        allows list owners to configure their lists with
root's avatar
root committed
230
        welcome, goodbye and other predefined messages using complex
231
232
233
234
235
236
237
238
239
        \textindex {MIME} structures. For example, a welcome message can be
        \textbf in {multipart/alternative} format, using \textbf {text/html},
        \textbf {audio/x-wav}~:-), or whatever (Note that \Sympa
        commands in multipart messages are successfully processed, provided that
	one part is \textbf {text/plain }).

    \item The \textbf {sending process is controlled} on a per-list basis.
        The list definition allows a number of different actions for
        each incoming message. A \lparam {private} list is a list where
root's avatar
root committed
240
241
        only subscribers can send messages. A list configured using
        \lparam {privateoreditorkey} mode accepts incoming messages
salaun's avatar
salaun committed
242
        from subscribers, but will forward any other (i.e. non-subscriber) message
243
244
245
	to the editor with a one-time secret numeric key that will be used by the
        editor to \textit {reject} or \textit {distribute} it.
        For details about the different sending modes, refer to the
root's avatar
root committed
246
247
        \lparam {send} parameter (\ref {par-send}, page~\pageref
        {par-send}). The sending process configuration (as well as most other list
248
	operations) is defined using  a \textbf {scenario}. Any listmaster
salaun's avatar
salaun committed
249
        can define new scenarios (scenarii) in order to complement the 20
250
251
252
	predefined configurations included in the distribution. \\
        Example : forward multipart messages to the list editor, while
	distributing others without requiring any further authorization.
root's avatar
root committed
253
        
254
255
    \item Privileged operations can be performed by list editors or
        list owners (or any other user category), as defined in the list
root's avatar
root committed
256
        \file {config} file or by
salaun's avatar
salaun committed
257
        the robot \textindex {administrator}, the listmaster, defined
root's avatar
root committed
258
        in the \file {/etc/sympa.conf} global configuration file.
259
260
261
262
263
264
        Privileged operations include the usual \mailcmd {ADD}, \mailcmd
        {DELETE} or \mailcmd {REVIEW} commands, which can be
        authenticated via a one-time password or an S/MIME signature.
	 Any list owner using the \mailcmd {EXPIRE}
        command can require the renewal of subscriptions. This is made
        possible by the presence of a subscription date stored in the
root's avatar
root committed
265
266
267
        \Sympa database.


268
269
270
271
    \item E-mail addresses can be retrieved dynamically from a database
    	accepting SQL queries, or from an LDAP directory. In the interest
	of reasonable response times, \Sympa retains the data source in an
	internal cache controlled by a TTL (Time To Live) parameter.
root's avatar
root committed
272

273
274
275
276
277
    \item Inclusion of the subscribers of one list among the subscribers of
    	another. This is real inclusion, not the dirty, multi-level cascading
	one might otherwise obtain by simply "subscribing list B to list A".
	 
    \item The internal subscriber data structure can be stored in a
root's avatar
root committed
278
        database or, for compatibility with versions 1.x, in text
279
        files. The introduction of databases came out of the
root's avatar
root committed
280
        \WWSympa project.  The database ensures a secure access to
281
        shared data. The PERL database API \textit {dbi/dbd} enables
root's avatar
root committed
282
283
284
285
286
        interoperability with various RDBMS (MySQL, PostgreSQL,
        Oracle, Sybase).

    \label {wwsympa} 
    \item {\WWSympa} is a global Web interface to all \Sympa functions
287
    	(including administration). It provides :
root's avatar
root committed
288
289
290

        \begin {itemize}

291
	    \item classification of lists, along with a search index
root's avatar
root committed
292

293
            \item access control to all functions, including the list of lists
294
                  (which makes WWSympa particularly well suited to be the main
295
		  groupware tool within an intranet)
root's avatar
root committed
296
 
297
       	    \item management of shared documents (download, upload, specific
root's avatar
root committed
298
299
		  access control for each document)

300
301
302
            \item an HTML document presenting each user with the list of
		  her current subscriptions, including access to archives, and
		  subscription options
root's avatar
root committed
303

304
305
            \item management tools for list managers (bounce processing, changing of
                  list parameters, moderating incoming messages)
root's avatar
root committed
306

307
308
            \item tools for the robot administrator (list creation, global robot
                  configuration) \index{administrator}
root's avatar
root committed
309
310
311
312
313
314
315
316
317
318

        \end {itemize}



\end {itemize}


\section {Project directions}

319
Future developments should include:
root's avatar
root committed
320
321
322

\begin {itemize}

323
    \item Virtual robot definition. ISPs would appreciate the
root's avatar
root committed
324
        equivalent of \htmladdnormallinkfoot {Apache} {http://www.apache.org}
325
        virtual server features applied to mailing lists.
root's avatar
root committed
326

327
    \item Additional groupware features such as a calendar, a scenario editor, etc
root's avatar
root committed
328

329
330
331
    \item Subscriber preference for multipart/alternative message reception.
          Some newspapers publish both text/plain and text/html version of
          their mails. It would be nice to provide a single list for both formats.
root's avatar
root committed
332
333
334
335
336

\end {itemize}

\section {History}

337
338
\Sympa development started from scratch in 1995. The goal was to
ensure continuity with the \textindex {TULP} list manager, produced
root's avatar
root committed
339
340
partly by the initial author of \Sympa: Christophe Wolfhugel.

341
342
343
344
New features were required, which the TULP code was just not up to
handling. The initial version of \Sympa brought authentication,
the flexible management of commands, high performances in internal
data access, and object oriented code for easy code maintenance.
root's avatar
root committed
345

346
It took nearly two years to produce the first market releases.
root's avatar
root committed
347
348
349
350

\section {Authors and credits}

Christophe Wolfhugel is the author of the first beta version of
351
\Sympa. He developed it while working for the
root's avatar
root committed
352
353
\htmladdnormallinkfoot {Institut Pasteur} {http://www.pasteur.fr}.

354
Later developments have mainly been driven by the
root's avatar
root committed
355
\htmladdnormallinkfoot {Comit\'e R\'eseaux des Universit\'es} {http://www.cru.fr}
356
(Olivier Sala\"un and Serge Aumont), who look after a large mailing
root's avatar
root committed
357
358
list service.

359
Our thanks to all contributors, including:
root's avatar
root committed
360
361
362
363
364

\begin {itemize}

   \item Pierre David, who in addition to his help and suggestions
       in developing the code, participated more than actively in
365
       producing this manual.
root's avatar
root committed
366
367

  \item Ollivier Robert, Usenet Canal Historique and the good manners
368
      guru in the PERL program.
root's avatar
root committed
369
370
371
372

  \item Rapha\"el Hertzog (debian) and St\'ephane Poirey (redhat) for
      Linux packages.

373
  \item Olivier Lacroix, for all his perseverance in bug fixing.
root's avatar
root committed
374

375
376
  \item Fabien Marquois, who introduced many new features such as
      the digest.
root's avatar
root committed
377

378
  \item Alex Nappa and Josep Roman for their Spanish translations
root's avatar
root committed
379

380
  \item Carsten Clasohm and Jens-Uwe Gaspar for their German translations
root's avatar
root committed
381

382
  \item Marco Ferrante for his Italian translations
root's avatar
root committed
383
384
385

  \item Hubert Ulliac for search in archive base on marcsearch.pm

386
  \item Tung Siu Fai for his Chinese translations
root's avatar
root committed
387
388
389
390
391

  \item and also: Manuel Valente, Dominique ROUSSEAU,
    Laurent Ghys, Francois Petillon, Guy Brand, Jean Brange, Fabrice
    Gaillard, Hervé Maza

392
   \item Anonymous critics who never missed a chance to
root's avatar
root committed
393
394
395
396
       remind us that \textit {smartlist} already did all that
       better.

   \item All contributors and beta-testers cited in the \file
397
       {RELEASE\_NOTES} file, who, by serving as guinea pigs and
root's avatar
root committed
398
399
400
401
402
403
404
405
       being the first to use it, made it possible to quickly and
       efficiently debug the \Sympa software.

    \item Bernard Barbier, without whom \Sympa would not
        have a name.

\end {itemize}

406
407
We ask all those we have forgotten to thank to accept our apologies
and to let us know, so that we can correct this error in future
root's avatar
root committed
408
409
releases of this documentation.

410
\section {Mailing lists and support}
root's avatar
root committed
411
412
413
414
415
    \label {sympa@cru.fr}

If you wish to contact the authors of \Sympa, please use the address
\mailaddr {sympa-authors{\at}cru.fr}.

416
There are also a few \htmladdnormallinkfoot {mailing-lists about \Sympa} {http://listes.cru.fr/wws/lists/informatique/sympa} :
root's avatar
root committed
417
418
419
420

	\begin {itemize}
	   \item  \mailaddr {sympa-users{\at}cru.fr} general info list
	   
421
	   \item   \mailaddr {sympa-fr{\at}cru.fr}, for French-speaking users
root's avatar
root committed
422
			   
423
	   \item   \mailaddr {sympa-announce{\at}cru.fr}, \Sympa announcements
root's avatar
root committed
424
			  
425
	   \item   \mailaddr {sympa-dev{\at}cru.fr}, \Sympa developers
root's avatar
root committed
426
427
428
429
430
431
432
433
434
435
436
			  
	\end {itemize}

To join, send the following message to \mailaddr {sympa{\at}cru.fr}:

\begin {quote}
    \texttt {subscribe} \textit {Listname} \textit {Firstname} \textit {Name}
\end {quote}

(replace \textit {Listname}, \textit {Firstname} and \textit {Name} by the list name, your first name and your family name).

437
438
You may also consult the \Sympa \htmladdnormallink {home page} {http://listes.cru.fr/sympa},
you will find the latest version, \htmladdnormallink {FAQ} {http://listes.cru.fr/sympa/fom-serve/cache/1.html} and so on.
root's avatar
root committed
439
440

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
441
% Overview: what does \Sympa consist of ?
root's avatar
root committed
442
443
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\cleardoublepage
444
\chapter {what does \Sympa consist of ?}
root's avatar
root committed
445
446
447
448
449
450
451
452

%\begin {htmlonly}
%<A NAME="overview">
%\end {htmlonly}

\section {Organization}
\label {organization}

453
454
Here is a snapshot of what \Sympa looks like once it has settled down
on your system. This also illustrates the \Sympa philosophy, I guess.
root's avatar
root committed
455
456
457
458

\begin {itemize}

	\item \tildedir {sympa/}\\
459
	The root directory of \Sympa. You will find almost everything
root's avatar
root committed
460
461
462
463
464
465
466
467
468
	related to \Sympa under this directory, except logs and main
	configuration files.
	
	\item \tildedir {sympa/bin/}\\
	This directory contains the binaries, including CGI. It
	also contains the default scenarios, templates and configuration
	files.

	\item \tildedir {sympa/bin/etc/}\\
469
470
	Here \Sympa stores the default versions of what it will otherwise find
	in \tildedir {sympa/etc/} (scenarios, templates and configuration
root's avatar
root committed
471
472
473
	files, recognized S/Mime certificates).

	\item \tildedir {sympa/etc/}\\
474
475
	This is your site's configuration directory. Consult
	\tildedir {sympa/bin/etc/} when drawing up your own.
root's avatar
root committed
476
477

	\item \tildedir {sympa/etc/create\_list\_templates/}\\
478
	List templates (suggested at list creation time).
root's avatar
root committed
479
480

	\item \tildedir {sympa/etc/scenari/}\\
481
482
	This directory will contain your scenarii (or scenarios, if you prefer).
	If you don't know what the hell a scenario is, refer to \ref {scenarii}, 
root's avatar
root committed
483
484
485
	page~\pageref {scenarii}.
	
	\item \tildedir {sympa/etc/wws\_templates/}\\
486
	The web interface (\WWSympa) is composed of template HTML
root's avatar
root committed
487
488
489
	files parsed by the CGI program.

	\item \tildedir {sympa/etc/templates/}\\
490
	Some of the mail robot's replies are defined by templates
root's avatar
root committed
491
	(\file{welcome.tpl} for SUBSCRIBE). You can overload
492
493
	these template files in the individual list directories, but these
	are the defaults.
root's avatar
root committed
494
495

	\item \tildedir {sympa/expl/}\\
496
	\Sympa's working directory.
root's avatar
root committed
497
498

	\item \tildedir {sympa/expl/\samplelist}\\
499
500
	The list directory (refer to \ref {list-directory}, 
	page~\pageref {list-directory}).
root's avatar
root committed
501
502
503

	\item \tildedir {sympa/nls/}\\
	Internationalization directory. It contains XPG4-compatible
504
505
	message catalogues. \Sympa has currently been translated
	into 8 different languages.
root's avatar
root committed
506
507

	\item \tildedir {sympa/spool/}\\
salaun's avatar
salaun committed
508
	\Sympa uses 7 different spools (see \ref{spools}, page~\pageref{spools}).
root's avatar
root committed
509
510

	\item \tildedir {sympa/src/}\\
511
	\Sympa sources.
root's avatar
root committed
512
513
514
515
516
517
518
519
520
521

\end {itemize}

\section {Binaries}
\label {binaries}

\begin {itemize}

	\item \file {sympa.pl}\\
	The main daemon ; it processes commands and delivers
522
	messages. Continuously scans the \dir {msg/} spool.
root's avatar
root committed
523
524

	\item \file {wwsympa.fcgi}\\
525
	The CGI program offering a complete web interface
root's avatar
root committed
526
	to mailing lists. It can work in both classical CGI and
527
	FastCGI modes, although we recommend FastCGI mode, being
root's avatar
root committed
528
529
530
	up to 10 times faster.

	\item \file {bounced.pl}\\
531
	This daemon processes bounces (non-delivered messages),
root's avatar
root committed
532
	looking for the bad addresses. List owners will later
533
534
	access bounce information via \WWSympa. Continuously scans
	the \dir {bounce/} spool.
root's avatar
root committed
535
536
537
538

	\item \file {archived.pl}\\
	This daemon feeds the web archives, converting messages
	to HTML format and linking them. It uses the amazing 
539
	\file {MhOnArc}. Continuously scans the \dir {outgoing/} 
root's avatar
root committed
540
541
542
543
	spool.

	\item \file {queue}\\
	This small program gets the incoming messages from the aliases
544
	and stores them in \dir {msg/} spool.
root's avatar
root committed
545
546

	\item \file {bouncequeue}\\
547
	Same as \file {queue} for bounces. Stores bounces in 
root's avatar
root committed
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
	\dir {bounce/} spool.

\end {itemize}

\section {Configuration files}

\begin {itemize}

	\item \file {sympa.conf}\\
	The main configuration file.
	See \ref{exp-admin}, page~\pageref{exp-admin}.
	

	\item \file {wwsympa.conf}\\
	\WWSympa configuration file.
	See \ref{wwsympa}, page~\pageref{wwsympa}.
	
	\item \file {edit\_list.conf}\\
566
	Defines which parameters/files are editable by
root's avatar
root committed
567
568
569
	owners. See \ref{list-edition}, page~\pageref{list-edition}.

	\item \file {topics.conf}\\
570
571
572
	Contains the declarations your site's topics (classification in
	\WWSympa), along with their titles. A sample is provided in the
	\dir {sample/} directory of the sympa distribution.
root's avatar
root committed
573
574
575
576
577
578
579
	See \ref{topics}, page~\pageref{topics}.

\end {itemize}

\section {Spools}
\label {spools}

salaun's avatar
salaun committed
580
581
582
See \ref{spool-related}, page~\pageref{spool-related} for spool definition
in \file {sympa.conf}.

root's avatar
root committed
583
584
585
\begin {itemize}

	\item \tildedir {sympa/spool/auth/}\\
586
	For storing messages until they have been confirmed.
root's avatar
root committed
587
588
589
590
591

	\item \tildedir {sympa/spool/bounce/}\\
	For storing incoming bouncing messages.

	\item \tildedir {sympa/spool/digest/}\\
592
	For storing lists' digests before they are sent.
root's avatar
root committed
593
594

	\item \tildedir {sympa/spool/expire/}\\
595
	Used by the expire process.
root's avatar
root committed
596
597
598
599
600
601
602
603

	\item \tildedir {sympa/spool/mod/}\\
	For storing unmoderated messages.

	\item \tildedir {sympa/spool/msg/}\\
	For storing incoming messages (including commands).

	\item \tildedir {sympa/spool/outgoing/}\\
604
605
	\file {sympa.pl} dumps messages in this spool to await archiving
	by \file {archived.pl}.
root's avatar
root committed
606
607
608
609
610
611
612
613
614
615
616
617
618
619

\end {itemize}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Installing Sympa
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\cleardoublepage
\chapter {Installing \Sympa}

%\begin {htmlonly}
%<A NAME="installsympa">
%\end {htmlonly}

620
\Sympa is a program written in PERL. It also calls a short
621
622
program written in C for tasks which it would be unreasonable to
perform via an interpreted language.
root's avatar
root committed
623

624
\section {Obtaining \Sympa, related links}
root's avatar
root committed
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644

The \Sympa distribution is available from
\htmladdnormallink {\texttt {http://listes.cru.fr/sympa/}}
    {http://listes.cru.fr/sympa/}.
All important resources are referenced there:

\begin {itemize}
    \item sources
    \item \file {RELEASE\_NOTES}
    \item .rpm and .deb packages for Linux
    \item user mailing list
        (see~\ref {sympa@cru.fr}, page~\pageref {sympa@cru.fr})
    \item contributions
    \item ...
\end {itemize}


\section {Prerequisites}

\Sympa installation and configuration are relatively easy
645
tasks for experienced UNIX users who have already installed PERL packages.
646
647
648
649
650
651
652
653

Note that most of the installation time will
involve putting in place the prerequisites, if they are not
already on the system. No more than a handful of ancillary tools are needed,
and on recent UNIX systems their installation is normally very
straightforward. We strongly advise you to perform installation steps and
checks in the order listed below; these steps will be explained in
detail in later sections.
root's avatar
root committed
654
655

\begin {itemize}
656
    \item identification of host system characteristics
root's avatar
root committed
657
658

    \item installation of DB Berkeley module (already installed on
659
      most UNIX systems)
root's avatar
root committed
660
661

    \item installation of
662
        \htmladdnormallinkfoot {CPAN (Comprehensive PERL Archive Network)}
root's avatar
root committed
663
                {http://www.perl.com/CPAN}
664
        modules
root's avatar
root committed
665

666
    \item creation of a UNIX user
root's avatar
root committed
667
668
669
670
671

\end {itemize}

\subsection {System requirements}

672
You should have a UNIX system that is more or less recent in order
root's avatar
root committed
673
to be able to use \Sympa. In particular, it is necessary
674
675
676
that your system have an ANSI C compiler (in other words, your compiler
should support prototypes), as well as XPG4-standard \textindex {NLS}
(Native Language Support, for languages other than English) extensions.
root's avatar
root committed
677
678
679
680
681
682
683

\Sympa has been installed and tested on the following
systems, therefore you should not have any special problems:

\begin {itemize}
    \item Linux (various distributions)
    \item FreeBSD 2.2.x and 3.x
684
    \item Digital UNIX 4.x
root's avatar
root committed
685
686
687
688
689
    \item Solaris 2.5 and 2.6
    \item AIX 4.x
    \item HP-UX 10.20
\end {itemize}

690
Anyone willing to port it to NT ? ;-)
root's avatar
root committed
691

692
If your UNIX system has a \unixcmd {gencat} command as well as
root's avatar
root committed
693
694
695
696
\unixcmd {catgets(3)} and \unixcmd {catopen(3)} functions, it is
likely that it has \textindex {NLS} extensions and that these extensions comply
with the XPG4 specifications.

697
Finally, most UNIX systems are now supplied with an ANSI C compiler;
root's avatar
root committed
698
699
700
701
if this is not the case, you can install the \unixcmd {gcc} compiler,
which you will find on the nearest GNU site, for example
\htmladdnormallinkfoot {in France} {ftp://ftp.oleane.net/pub/mirrors/gnu/}.

702
703
To complete the installation, you should make sure that you have a
sufficiently recent release of the \unixcmd {sendmail} MTA, i.e. release
root's avatar
root committed
704
705
706
707
708
709
\htmladdnormallinkfoot {8.9.x} {ftp://ftp.oleane.net/pub/mirrors/sendmail-ucb/}
or a more recent release. You may also use \unixcmd {postfix} or
\unixcmd {qmail}.

\subsection {Install Berkeley DB (NEWDB)}

710
UNIX systems often include a particularly unsophisticated mechanism to
711
712
713
manage indexed files.  This consists of extensions known as \texttt {dbm}
and \texttt {ndbm}, which are unable to meet the needs of many more recent
programs, including \Sympa, which uses the \textindex {DB package}
root's avatar
root committed
714
715
716
initially developed at the University of California in Berkeley,
and which is now maintained by the company \htmladdnormallinkfoot
{Sleepycat software} {http://www.sleepycat.com}.  Many UNIX  systems
717
like Linux, FreeBSD or Digital UNIX 4.x have the DB package in the
root's avatar
root committed
718
719
720
721
standard version. If not you should install this tool if you have not 
already done so.

You can retrieve DB on the
722
723
\htmladdnormallinkfoot {Sleepycat site} {http://www.sleepycat.com/},
where you will also find clear installation instructions.
root's avatar
root committed
724

725
\subsection {Install PERL and CPAN modules}
root's avatar
root committed
726

727
To be able to use \Sympa you must have release 5.004\_03 or later of the
728
PERL language, as well as several CPAN modules.
root's avatar
root committed
729

730
At \texttt {make} time, the \unixcmd {check\_perl\_modules.pl} script is run to
731
check for installed versions of required PERL and CPAN modules. If a CPAN module is
root's avatar
root committed
732
733
734
missing or out of date, this script will install it for you. 

You can also download and install CPAN modules yourself. You will find 
735
a current release of the PERL interpreter in the nearest CPAN archive. 
root's avatar
root committed
736
If you do not know where to find a nearby site, use the
737
\htmladdnormallinkfoot {CPAN multiplexor} {http://www.perl.com/CPAN/src/latest.tar.gz};
root's avatar
root committed
738
739
740
741
it will find one for you.

\subsection {Required CPAN modules}

742
The following CPAN modules required by \Sympa are not included in the standard
743
PERL distribution. We try to keep this list up to date ; if you have any doubts
744
run the \unixcmd {check\_perl\_modules.pl} script.
root's avatar
root committed
745
746

\begin {itemize}
747
   \item DB\_File (v. 1.50 or later)
root's avatar
root committed
748
749
   \item Msgcat
   \item MD5
750
   \item MailTools (version 1.13 o later)
root's avatar
root committed
751
752
753
754
   \item MIME-tools (may require IO/Stringy)
   \item MIME-Base64
\end {itemize}

755
Since release 2, \Sympa requires an RDBMS to work properly. It stores 
756
users' subscriptions and preferences in a database. \Sympa is also
root's avatar
root committed
757
able to extract user data from within an external database. 
758
These features require that you install database-related PERL libraries.
root's avatar
root committed
759
760
761
762
763
764
765
766
767
768
769
770
This includes the generic Database interface (DBI) and a Database Driver
for your RDBMS (DBD) :

\begin {itemize}
   \item \textbf {DBI} (DataBase Interface)

   \item \textbf {DBD} (DataBase Driver) related to your RDBMS (e.g.
       Msql-Mysql-modules for MySQL)

\end {itemize}

If you plan to interface \Sympa with an LDAP directory to build
771
dynamical mailing lists, you need to install PERL LDAP libraries :
root's avatar
root committed
772
773
774
775
776
777

\begin {itemize}
    \item \textbf {Net::LDAP} (perlldap).

\end {itemize}

778
\subsection {Create a UNIX user}
root's avatar
root committed
779

780
The final step prior to installing \Sympa: create a UNIX user (and
781
if possible a group) specific to the program. Most of the installation
root's avatar
root committed
782
783
784
will be carried out with this account. We suggest that you use the
name \texttt {sympa} for both user and group. Note that UID.GID must be
the same as your httpd. If you are running a dedicated httpd server,
785
this can be sympa.sympa, otherwise it is possible either to define a virtual httpd
salaun's avatar
salaun committed
786
server setting UID.GID, or to run \Sympa as nobody.nobody. 
787
This second solution is not advisable because the information managed by \Sympa
root's avatar
root committed
788
789
will be owned by nobody.

790
791
792
Numerous files will be located in the \Sympa user's login directory.
Throughout the remainder of this documentation we shall refer to this
login directory as \tildedir {sympa/}.
root's avatar
root committed
793
794
795

\section {Compilation and installation }

796
797
Before using \Sympa, you must customize the sources in order to
specify a small number of parameters specific to your installation.
root's avatar
root committed
798

799
First, extract the sources from the archive file, for example
root's avatar
root committed
800
801
802
803
from the \tildedir {sympa/} directory: the archive will create a
directory named \dir {sympa-\version/} where all the useful files
and directories will be located. In particular, you will have a
\dir {doc/} directory containing this documentation in various
804
805
806
formats; a \dir {sample/} directory containing a few examples of
configuration files; an \dir {nls/} directory where multi-lingual
messages are stored; and, of course, the \dir {src/} directory for the
root's avatar
root committed
807
808
809
810
811
812
813
814
815
816
mail robot and \dir {wwsympa} for the web interface.

Example:

\begin {quote}
\tt
\# su - \\
\$ gzip -dc sympa-\version.tar.gz | tar xf -
\end {quote}

817
818
\label {makefile}

root's avatar
root committed
819
Before running \unixcmd {make} in the main
820
821
822
directory, you should edit and configure \file {Makefile},
the first part of which requires customization.
We advise against changing anything located after the STOP
root's avatar
root committed
823
824
825
line.

The \file {Makefile} file contains explanations for the fields,
826
which you may have to change. They main ones are :
root's avatar
root committed
827
828
\begin {itemize}
\item USER and GROUP, the id of daemons.
829
\item CONFIG and WWSCONFIG, the location of robot and cgi configurations
root's avatar
root committed
830
831
\item DIR, the \Sympa home dir
\item MAILERPROGDIR, the location of queue and bouncequeue programs. If sendmail
832
833
834
is configured to use smrsh (check the mailer prog definition in your sendmail.cf),
queue and bouncequeue need to be installed in /etc/smrsh.  This is probably
the case if you are using redhat 6.X.
835
836
837
\item SENDMAIL\_ALIASES, the sendmail aliases file. This is used by the alias\_manager
script.
\item NEWALIASES, the path to newaliases command.
838
839
\item INITDIR, the directory to contain a SYSV init script (typically /etc.rc.d/init.d/)
\item DESTDIR, can be set in the main Makefile to install sympa in DESTDIR/DIR
840
841
(instead of DIR). This is useful for building RPM and DEB packages.
\item PERL, SH and CC and GENCAT, respectively perl, sh, cc and gencat locations. 
root's avatar
root committed
842
\item DARK\_COLOR, LIGHT\_COLOR, TEXT\_COLOR, BG\_COLOR, ERROR\_COLOR to define wwsympa
843
RGB colors
root's avatar
root committed
844
845
\end {itemize}

846
847
Once this file has been configured, you need to run the \texttt {make;make~install} commands.
This generates the binary for the \file {queue} program along with the nls, and inserts
root's avatar
root committed
848
the \Sympa and \WWSympa programs in their final slot, while having propagated
849
850
a few parameters into the PERL files, such the access path
to the PERL program. The make command includes the checking of CPAN modules.
root's avatar
root committed
851
852
 
If everything goes smoothly, the \tildedir {sympa/bin/} directory
853
will contain various PERL programs as well as the \file {queue}
854
binary.  You will remark that this binary has the \index{set-uid-on-exec
root's avatar
root committed
855
bit} \textit {set-uid-on-exec} bit (owner is the \texttt {sympa}
856
user): this is deliberate, and indispensable if \Sympa is to run correctly.
root's avatar
root committed
857

858
\subsection {Choosing directory locations}
root's avatar
root committed
859

860
861
862
863
All directories are defined in the \file {/etc/sympa.conf} file, which
is read by \Sympa at runtime. If no \file {sympa.conf} file
was found during installation, a sample one will be created.
For the default organization of directories, please refer to \ref {organization}, 
root's avatar
root committed
864
865
page~\pageref {organization}.

866
867
868
It would, of course, be possible to disperse files and directories to a number of different
locations. However, we recommend storing all the directories and files in  the \texttt {sympa}
user's login directory.
root's avatar
root committed
869

870
These directories must be created manually now. You can use restrictive
root's avatar
root committed
871
authorizations if you like, since only programs running with the
872
\texttt {sympa} account will need to access them.
root's avatar
root committed
873
874
875
876
877
878


\section {Robot aliases}
    \index{aliases}
    \index{mail aliases}

879
An electronic list manager such as \Sympa is built around two processing steps:
root's avatar
root committed
880
881
882
883
884
885
886

\begin {itemize}
    \item a message sent to a list or to \Sympa itself
        (for subscribe, unsubscribe, help messages, etc.) is received
        by the SMTP server (\unixcmd {sendmail} or \unixcmd {qmail}).
        The SMTP server, on reception of this message, runs the
        \file {queue} program (supplied in this package) to store
887
        the message in a queue, i.e. in a special directory.
root's avatar
root committed
888

889
890
    \item the \file {sympa.pl} daemon, set in motion at
        system startup, scans the queue. As soon as it
root's avatar
root committed
891
892
893
894
895
896
        detects a new message, it processes it and performs the
        requested action (distribution or processing of an
        administrative request).

\end {itemize}

897
898
899
900
901
To separate the processing of administrative requests (subscription,
unsubscription, help requests, etc.) from the processing of messages destined for mailing
lists, a special mail alias is reserved for administrative requests, so
that \Sympa can be permanently accessible to users. The following
lines must therefore be added to the \unixcmd {sendmail} alias file
root's avatar
root committed
902
903
904
905
906
907
908
909
910
911
912
913
914
(often \file {/etc/aliases}):

\begin {quote}
\begin{verbatim}
sympa:             "| /home/sympa/bin/queue sympa"
listmaster: 	   "| /home/sympa/bin/queue listmaster"
bounce+*:          "| /home/sympa/bin/bouncequeue sympa"
sympa-request:     postmaster
sympa-owner:       postmaster
\end{verbatim}
\end {quote}

\mailaddr {sympa-request} should be the address of the robot
915
916
\textindex {administrator}, i.e. a person who looks after
\Sympa (here \mailaddr {postmaster{\at}cru.fr}).
root's avatar
root committed
917
918
919
920

\mailaddr {sympa-owner} is the return address for \Sympa error
messages.

921
922
The alias bounce+* is dedicated to collect bounces. It is useful
only if at least one list uses \texttt { welcome\_return\_path unique } or
root's avatar
root committed
923
\texttt { remind\_return\_path unique}.
924
Don't forget to run \unixcmd {newaliases} after any change to
root's avatar
root committed
925
926
927
the \file {/etc/aliases} file!

Note: aliases based on \mailaddr {listserv} (in addition to those
928
929
930
based on \mailaddr {sympa}) can be added for the benefit of users
accustomed to the \mailaddr {listserv} and \mailaddr {majordomo} names.
For example:
root's avatar
root committed
931
932
933
934
935
936
937
938
939
940
941

\begin {quote}
\begin{verbatim}
listserv:          sympa
listserv-request:  sympa-request
majordomo:         sympa
listserv-owner:    sympa-owner
\end{verbatim}
\end {quote}

Note: it will also be necessary to add entries in this alias file
942
when lists are created (see list creation section, \ref {list-aliases},
root's avatar
root committed
943
944
945
946
947
page~\pageref {list-aliases}).


\section {Logs}

948
949
950
951
952
953
954
\Sympa keeps a trace of each of its procedures in its log file.
However, this requires configuration of the \unixcmd {syslogd}
daemon.  By default \Sympa wil use the \texttt {local1} facility
(\lparam {syslog} parameter in \file {sympa.conf}).
WWSympa's logging behaviour is defined by the \lparam {log\_facility}
parameter in \file {wwsympa.conf} (by default the same facility as \Sympa).\\
To this end, a line must be added in the \unixcmd {syslogd} configuration file (\file
root's avatar
root committed
955
956
957
958
959
960
961
962
963
964
965
{/etc/syslog.conf}). For example:

\begin {quote}
\begin{verbatim}
local1.*       /var/log/sympa 
\end{verbatim}
\end {quote}

Then reload \unixcmd {syslogd}.

Depending on your platform, your syslog daemon may use either
966
967
a UDP or a UNIX socket. \Sympa's default is to use a UNIX socket;
you may change this behavior by editing \file {sympa.conf}'s
root's avatar
root committed
968
969
970
\lparam {log\_socket\_type} parameter (\ref{par-log-socket-type},
page~\pageref{par-log-socket-type}).

salaun's avatar
salaun committed
971
972
\section {sympa.pl}
\label{sympa.pl}
root's avatar
root committed
973

974
Once the files are configured, all that remains is to start \Sympa.
root's avatar
root committed
975
976
977
978
979
980
981
982
983
984
985
986
987
988
At startup, \file {sympa.pl} will change its UID to sympa (as defined in \file {Makefile}).
To do this, add the following sequence or its equivalent in your
\file {/etc/rc.local}:

\begin {quote}
\begin{verbatim}

~sympa/bin/sympa.pl
~sympa/bin/archived.pl
~sympa/bin/bounced.pl

\end{verbatim}
\end {quote}

989
\file {sympa.pl} recognizes the following command line arguments:
root's avatar
root committed
990
991
992

\begin {itemize}

salaun's avatar
salaun committed
993
\item --debug | -d 
root's avatar
root committed
994
995
  
  Sets \Sympa in debug mode and keeps it attached to the terminal. 
996
  Debugging information is output to STDERR, along with standard log
997
  information. Each function call is traced. Useful while reporting
salaun's avatar
salaun committed
998
  a bug.
root's avatar
root committed
999
  
salaun's avatar
salaun committed
1000
\item --config | -f \textit {config\_file}
For faster browsing, not all history is shown. View entire blame