Commit | Line | Data |
---|---|---|
f8beb284 MW |
1 | $Id: INSTALL.idx,v 1.49 1999/12/24 20:12:57 lindberg Exp $ |
2 | $Name: ezmlm-idx-040 $ | |
3 | ||
4 | Like any other piece of software (and information generally), ezmlm-idx | |
5 | comes with NO WARRANTY. | |
6 | ||
7 | This file is for installing ezmlm-idx for the first time on a system | |
8 | that may have ezmlm-0.53. If you're already using ezmlm-idx, see | |
9 | UPGRADE.idx instead. | |
10 | ||
11 | Things you have to decide before starting: | |
12 | ||
13 | Common for ezmlm-0.53: | |
14 | Put the desired ezmlm bin path into conf-bin. Default "/usr/local/bin/ezmlm", | |
15 | but for e.g. rpm packages it's "/usr/bin". Adjust conf-man accordingly. | |
16 | For installations (e.g. Debian) where qmail is not in "/var/qmail", adjust | |
17 | conf-qmail. | |
18 | ||
19 | NOTE: If you follow the test instructions in INSTALL of ezmlm-0.53 after | |
20 | adding ezmlm-idx, step 6 will fail. Before this step, edit | |
21 | ~/testlist/editor and remove the ezmlm-reject line. | |
22 | ||
23 | HOW TO BUILD, TEST, AND INSTALL: | |
24 | ||
25 | 1. Expand the ezmlm-0.53.tar.gz archive. expand the ezmlm-idx-0.xx.tar.gz | |
26 | archive: | |
27 | % zcat ezmlm-0.53.tar.gz | tar -xvf | |
28 | % zcat ezmlm-idx-0.xx.tar.gz | tar -xvf | |
29 | ||
30 | 2. Copy the contents of the archive to your ezmlm-0.53 directory. | |
31 | % mv ezmlm-idx-0.xx/* ezmlm-0.53/ | |
32 | ||
33 | 3. Patch the ezmlm-0.53 source: | |
34 | % cd ezmlm-0.53 | |
35 | % patch < idx.patch | |
36 | ||
37 | If you patch utility failes with this, get GNU patch. | |
38 | [ezmlm-issubn, an enhanced version of ezmlm-issub is part of this package. | |
39 | The patch for the ezmlm-return bug is also part of this package.] | |
40 | ||
41 | 4. If your 'crontab' binary does not live in '/usr/bin' edit 'conf-cron' | |
42 | now to reflect the correct path. | |
43 | ||
44 | 5. RDBM Support. | |
45 | ||
46 | MySQL: | |
47 | If you want to compile ezmlm with MySQL support (http://www.tcx.se), | |
48 | edit sub_mysql/conf-sqlcc (include files) and mysql/conf-sqlld (libraries) | |
49 | to reflect your MySQL installation (see MySQL documentation). The files | |
50 | are preset for RedHat Linux-i386. On some systems, the ``-lnsl'' should | |
51 | be removed from conf-sqlld. The package has been tested with MySQL 3.22. | |
52 | ||
53 | (Programs compiled with MySQL support will work like | |
54 | their non-MySQL counterparts for lists that are not specifically | |
55 | set up to take advantage of MySQL support.) Do: | |
56 | % make mysql | |
57 | ||
58 | PostgresSQL: | |
59 | If you want to compile ezmlm with PostgreSQL support | |
60 | (http://www.postgreSQL.org), edit sub_pgsql/conf-sqlcc (include files) | |
61 | and pgsql/conf-sqlld (libraries) to reflect your PostgreSQL installation | |
62 | (see PostgreSQL documentation). Do: | |
63 | % make pgsql | |
64 | ||
65 | Others: | |
66 | If you're familiar with C programming for the particular RDBMS, it will | |
67 | take you no more than a few hours to adapt the files in sub_mysql (see | |
68 | docs there). Create a new sub_????, tar and gzip it and send it to | |
69 | lindberg#@id.wustl.edu for inclusion into the package. | |
70 | ||
71 | 6. Compile the programs and man pages: | |
72 | % make clean | |
73 | % make; make man | |
74 | ||
75 | 7. To use a language other than US English as the default for list texts: | |
76 | % make ISO | |
77 | ||
78 | where ``iso'' is the ISO language designation. Currently supported | |
79 | are: cz, da, de, en_US, fr, jp, pl, pt_BR, sv. NOTE: A normal ``make'' sets | |
80 | up the en_US version (as before). ezmlmrc files for your language | |
81 | may be available via ftp://id.wustl.edu/pub/patches/ezmlmrc. If not, | |
82 | please feel free to contribute one (translate ezmlmrc.en_US, but leave | |
83 | comments intact for "diff"). | |
84 | ||
85 | 8. Test the programs: | |
86 | a. Create a user ``eztest'' or edit ezmlm-test to use another user name. | |
87 | This user should be able to execute the new binaries and also needs | |
88 | to have read access to ezmlm-test (chmod 755 ezmlm-test). | |
89 | b. Change to that user. | |
90 | c. From the build directory, execute ezmlm-test: | |
91 | % ./ezmlm-test | |
92 | ||
93 | ezmlm-test will set up a test list, execute the various programs, and | |
94 | test most functions of most programs. It works only if your qmail | |
95 | installation works and allows sending mail to the local user. If you | |
96 | use another user name, add ``-u other_user_name''. NOTE that the | |
97 | arguments must be separated by a space from the switches. | |
98 | ||
99 | Occasionally, ezmlm-test fails. This is usually due to problems with | |
100 | ezmlm-test on your particular platform/installation and not due to | |
101 | problems in ezmlm-idx. Please report problems with ezmlm-test, and if | |
102 | you can, patches for correcting it. | |
103 | ||
104 | ||
105 | 9. To test the SQL functions, set up a mysql database ``ezmlm'' accessible | |
106 | to a user at this host (see MySQL/PostgreSQL docs; the ezmlm-mktab script | |
107 | creates the necessary tables (see man page) but you must first create a | |
108 | database and a user with sufficient access. | |
109 | ||
110 | The following command creates a database for use with ezmlm-test. | |
111 | NOTE that ezmlm-mktab and ezmlm-test options must be separated from the | |
112 | switch, whereas the passwd argument for mysql -p must immediately | |
113 | follow the switch. | |
114 | % ./ezmlm-mktab -d list | mysql -hhost -uuser -ppasswd -f ezmlm | |
115 | ||
116 | or for PostgresSQL: | |
117 | % ./ezmlm-mktab -d list | pgsql [...] ezmlm | |
118 | ||
119 | Now, as the ``eztest'' user, execute: | |
120 | % ./ezmlm-test -l user -p passwd -h host | |
121 | ||
122 | This will test the SQL part of the binaries. ``host'' defaults to | |
123 | ``localhost'' and ``user'' defaults to ``ezmlm''. There is no default | |
124 | for passwd and indeed ezmlm-test uses this switch to know to work | |
125 | with SQL support. To execute under a user other than ``eztest'', | |
126 | add a ``-u testuser'' switch. Note that -p has to be specified even if | |
127 | the database has no password. In this case, use -p ''. | |
128 | ||
129 | 10. If you for some reason want to rebuild binaries without MySQL support, do: | |
130 | % make std | |
131 | % make | |
132 | ||
133 | 11. Copy binaries and man pages to the correct locations. | |
134 | # make setup | |
135 | (or copy manually). | |
136 | If you'd like to retest the installation, change uid to the test user | |
137 | ``eztest'' and change to the ezmlm binary directory. Now run ezmlm-test | |
138 | as before. | |
139 | ||
140 | ||
141 | 12. Your lists will run as before. To enable ezmlm-idx features like | |
142 | threaded archive access, digest, etc, use: | |
143 | ||
144 | % ezmlm-make -e [switches] DIR dot local host | |
145 | ||
146 | where ``DIR dot local host'' are the arguments used to create the list, | |
147 | and ``switches'' are desired options (see ezmlm-make man page). Future | |
148 | adjustments can be made with: | |
149 | ||
150 | % ezmlm-make -+ [switches] DIR | |
151 | ||
152 | where ``switches'' are desired _changes_ from the previous configuration. | |
153 | ||
154 | ------ OPTIONAL ------ | |
155 | ||
156 | 13. If you want qmail to add a subscriber-adapted List-Unsubscribe header to | |
157 | outgoing messages, apply the enclosed qmail-verh-0.03.tar.gz patch to | |
158 | qmail-1.03 and follow the documentation in that archive. This is a | |
159 | failsafe way in which to unsubscribe, even if subscriber or list have | |
160 | changed address. | |
161 | ||
162 | 14. If you want to use large lists with custom QMQP servers, apply the | |
163 | qmail-qmqp.tar.gz patch per instructions in the archive. You need this | |
164 | only if you want per-[sub]list control over the QMQP servers used. | |
165 | ||
166 | 15. (This can be done later if you decide to use ezmlm-cron(1). It is not | |
167 | needed for normal lists and mainly for ``legacy installations''.) | |
168 | The ezmlm-cron(1) program can be run SUID/SGID a special user with crond | |
169 | access. This allows your users to use ezmlm-cron to generate digest | |
170 | trigger messages, without being able to directly use crond. To enable | |
171 | this feature create a special user, e.g. "ezmlm". Then: | |
172 | ||
173 | # chown ezmlm /usr/local/bin/ezmlm-cron | |
174 | # chmod 4555 /usr/local/bin/ezmlm-cron | |
175 | ||
176 | and create ~ezmlm/ezcronrc as described in the ezmlm-cron(1) man | |
177 | page. You may need to modify the path in the commands above if | |
178 | you have installed ezmlm in a non-default location. ezmlm-cron refuses | |
179 | to run SUID root. | |
180 | ||
181 | This user can read its crontab file which may contain digest codes from | |
182 | other users. Thus, this should be a reserved user name, not one of an | |
183 | ordinary user. | |
184 | ||
185 | ||
186 | 16. If you would like to make your archived lists available via the World | |
187 | Wide Web, you must install the ezmlm-cgi program which comes with | |
188 | ezmlm-idx versions starting with ezmlm-idx-0.40. When ezmlm-idx is compiled | |
189 | with the 'make' command, ezmlm-cgi is compiled also, however, it is not | |
190 | installed. Installation of the program allows one to view the archives by | |
191 | date, thread and author. See, ezmlm-cgi.1 for more details. | |
192 | ||
193 | 17. ezmlm-cgi must be installed where all other common gateway interface | |
194 | ("CGI") programs are installed on your system. For most Un*x based system, | |
195 | this will be in a directory titled 'cgi-bin' which is also, generally | |
196 | speaking, in the root directory for your web server. For example, for apache | |
197 | installations where /usr/local/apache is the root directory for the web | |
198 | server, the directory /usr/local/apache/cgi-bin is where globally availably | |
199 | CGI programs are located. You must copy the ezmlm-cgi program to this | |
200 | location: | |
201 | ||
202 | % cp /ezmlm-0.53/ezmlm-cgi /usr/local/apache/cgi-bin | |
203 | ||
204 | 18. ezmlm-cgi should be installed SUID root. Examine the source code to make | |
205 | yourself comfortable that the program is safe. After copying the program to | |
206 | the 'cgi-bin' directory, change the ownerships and permissions as follows: | |
207 | ||
208 | % chown root.root ezmlm-cgi | |
209 | % chmod 4755 ezmlm-cgi | |
210 | ||
211 | If you are using ezmlm-cgi for a single user, you can install it SUID that | |
212 | user and place the config file (see below) as .ezcgirc in the same directory | |
213 | as the program. If the list archive is readable to the httpd user, you do | |
214 | not have to install it SUID at all (see man page for details). | |
215 | ||
216 | 19. ezmlm-cgi uses a configuration files called 'ezcgirc' which must reside | |
217 | in the /etc/ezmlm directory. First create the directory: | |
218 | ||
219 | % mkdir /etc/ezmlm | |
220 | ||
221 | Then use your favorite text editor to create the ezcgirc file. | |
222 | ||
223 | The file parameters are set forth on the first line. Comments are | |
224 | allowed if preceded by the '#' in position 1. Lists are input by number | |
225 | which is an arbitrary identifier with the exception of list '0' which is the | |
226 | default list shown on the web page. As an example, the following utilizes a | |
227 | list 'test@example.com' which is owned by the 'alias' user with a UID of | |
228 | 7827. The list resides in the directory '/var/qmail/alias/test' and its home | |
229 | page is at 'http://www.example.com/test'. With the foregoing setup, the | |
230 | ezcgirc file's contents are as follows: | |
231 | ||
232 | # Format for ezcgirc file | |
233 | #listno;uid;listdir;listaddr;buttonbar;charset;style;bannerprog | |
234 | 0;7827;/var/qmail/alias/test;test@example.com;[Home]=http://www.example.com/test | |
235 | ||
236 | Note there are no entries for 'charset', 'style' and 'bannerprog' Where | |
237 | no entries are made, the default variables are assumed. The above | |
238 | configuration assumes that the character set 'iso-8859-1' and that no | |
239 | style sheet is used. Since formatting is largely controlled by the | |
240 | style sheet, the output doesn't look exciting on a GUI browser. Start with | |
241 | ezcgi.css in the distribution, and modify to taste. See www.ezmlm.org | |
242 | for URLs to archives using different style sheets/banners. | |
243 | ||
244 | 20. Finally, before accessing the list via the web, you must archive any | |
245 | existing list and add an entry to listdir/editor to archive future posts. | |
246 | You must also run ezmlm-idx (first see man pages for both programs): | |
247 | ||
248 | % ezmlm-idx DIR | |
249 | % ezmlm-archive -c DIR | |
250 | ||
251 | 21. For any existing lists which you would like to archive, | |
252 | add the following line after the call to ezmlm-send in listdir/editor: | |
253 | ||
254 | | /usr/local/ezmlm/ezmlm-archive listdir/DIR || exit 0 | |
255 | ||
256 | This is automatically done when running: | |
257 | ||
258 | % ezmlm-make -+i DIR | |
259 | ||
260 | 22. To display your web based archive, open your browser as follows: | |
261 | ||
262 | %lynx http://localhost/cgi-bin/ezmlm-cgi | |
263 | ||
264 | ------------- End Optional items ----------- | |
265 | ||
266 | 23. That's it! To report success (helps to track platform-specific problems): | |
267 | ||
268 | % ( echo 'First M. Last'; cat `cat SYSDEPS` ) \ | |
269 | | mail cfl-src@id.wustl.edu | |
270 | ||
271 | Replace First M. Last with your name. | |
272 | ||
273 | Send bugs reports, ideally with patch, to 'lindberg@id.wustl.edu'. | |
274 |