| 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 | |