You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

INSTALL 15KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489
  1. SNFServer Installation and Configuration
  2. Copyright (C) 2008 ARM Research Labs, LLC.
  3. See www.armresearch.com for the copyright terms.
  4. Installing SNFServer to filter email involves the following steps:
  5. 1) Check prerequisites.
  6. 2) Create the snfilter user and group.
  7. 3) Build and install the SNFServer package (using a tarball or a
  8. package).
  9. 4) Configure the SNFServer package.
  10. 5) Interface with the MTA (postfix or sendmail).
  11. 6) Configure the OS to start and stop SNFServer on bootup and
  12. shutdown.
  13. The following sections describes each of these steps for a default
  14. installation. Any OS-specific issues are described at the end of each
  15. section.
  16. Prerequisites
  17. *************
  18. Before installing SNFServer, make sure that:
  19. 1) The program curl must be installed.
  20. Creating the snfilter user and group
  21. ************************************
  22. Before installing, the snfilter user and group must be created. For
  23. increased security, snfilter user has no shell.
  24. OS-specific issues--
  25. The commands to create the snfilter user and group are OS dependent.
  26. For your convenience, the commands for creating the user and group for
  27. varous OSes are listed here. However, no guarantee is made that these
  28. commands will work on your system; please refer to your system
  29. documentation.
  30. 1) OpenBSD:
  31. a) 'useradd -g =uid -m -c "SNFServer Account" -s /bin/false snfilter'.
  32. 2) Ubuntu:
  33. a) 'adduser --gecos "SNFServer Account" --no-create-home --shell /bin/false snfilter'.
  34. 3) RedHat (and variants such as Fedora and CentOS):
  35. a) 'adduser --comment "SNFServer Account" -M --shell /bin/false snfilter'
  36. 4) Suse:
  37. a) 'groupadd snfilter'
  38. b) 'useradd -c "SNFServer Account" -s /bin/false -g snfilter snfilter'
  39. 5) FreeBSD:
  40. a) 'pw user add -c "SNFServer Account" -n snfilter -w no -s /bin/false'
  41. Building and installing SNFServer
  42. *********************************
  43. For some operating systems, configuration files are normally installed
  44. in /etc, and the installation of the remaining files are in /usr
  45. (i.e. /usr/sbin, /usr/share/snf-server, etc). In other operating
  46. systems, the files are installed in /usr/local/etc or /usr/local.
  47. The directories to install are specified by the '--prefix' and
  48. '--sysconfdir' options to the configure script (see below).
  49. To build and install from the tarball--
  50. 1) Extract the distribution from the tarball: 'tar xvzf
  51. snf-server-X.Y.Z.tar.gz', where X.Y.Z is the version of the
  52. distribution.
  53. 1) 'cd' to the source directory.
  54. 2) Run the configure script. See the section on OS-specific issues
  55. for the options to specify. This configures the package.
  56. 3) Type 'make'. This builds the package.
  57. 4) Type 'make install'. This installs the package in the default
  58. directories.
  59. The following files are installed:
  60. Executables and scripts in sbin:
  61. SNFServer
  62. SNFClient
  63. SNF2Check
  64. getRulebase.sample
  65. snfSniffer.sample
  66. snfSnifferFilter.sample
  67. snfscan-standalone.sample
  68. snfServerControl.sample
  69. Sample configuration files in etc/snf-server:
  70. SNFServer.xml.sample
  71. identity.xml.sample
  72. In share/snf-server
  73. GBUdbIgnoreList.txt.sample
  74. During operation of SNFServer, the following files are created:
  75. In share/snf-server:
  76. *.snf
  77. Log files
  78. UpdateReady.txt
  79. Temporary files
  80. OS-specific options for ./configure:
  81. 1) OpenBSD:
  82. ./configure --enable-os-type=OpenBSD --sysconfdir=/etc
  83. 2) FreeBSD:
  84. ./configure --enable-os-type=FreeBSD
  85. 3) Ubuntu:
  86. ./configure --enable-os-type=Ubuntu --sysconfdir=/etc --prefix=/usr
  87. 4) RedHat (and variants such as Fedora and CentOS):
  88. ./configure --enable-os-type=RedHat --sysconfdir=/etc --prefix=/usr
  89. 5) Suse:
  90. ./configure --enable-os-type=Suse --sysconfdir=/etc --prefix=/usr
  91. Configuration
  92. *************
  93. Configuration consists of creating the configuration files used by
  94. SNFServer from the sample configuration files of the distribution.
  95. There are three configuration files. The location of the files
  96. described in this section are for the installation in /usr and /etc.
  97. Two of the files are in /etc/snf-server:
  98. 1) SNFServer.xml (sample configuration file is
  99. SNFServer.xml.sample).
  100. 2) identity.xml (sample configuration file is identity.xml.sample).
  101. and one in /usr/share/snf-server:
  102. 1) GBUdbIngoreList.txt (sample configuration file is
  103. GBUdbIgnoreList.txt.sample).
  104. To configure SNFServer, do the following:
  105. 1) Copy SNFServer.xml.sample to SNFServer.xml, and edit as follows:
  106. a) Specify the directories. The default directories are:
  107. <node identity='/etc/snf-server/identity.xml'>
  108. <log path='/usr/share/snf-server/'/>
  109. <rulebase path='/usr/share/snf-server/'/>
  110. <workspace path='/usr/share/snf-server/'/>
  111. <update-script on-off='on' call='/usr/sbin/getRulebase'
  112. guard-time='180'/>
  113. The paths need to be changed only if the default directories are
  114. not used.
  115. If desired for security purposes, restrict the permissions of
  116. SNFServer.xml. For example, to make SNFServer.xml readonly by
  117. only the snfilter user and snfilter group, enter the following:
  118. chmod 440 SNFServer.xml
  119. 2) Copy identity.xml.sample to identity.xml, and edit to include the
  120. license ID and authentication attributes of the <identity> element.
  121. If desired for security purposes, restrict the permissions of
  122. identity.xml. For example, to make identity.xml readonly by only
  123. snfilter, enter the following:
  124. chmod 400 identity.xml
  125. 3) Copy GBUdbIngoreList.txt.sample to GBUdbIgnoreList.txt, and edit
  126. as appropriate (the file format is described in the comments in the
  127. file). See README for more information on this file.
  128. 4) In the directory for the update script specified in the
  129. configuration file (default: /usr/sbin):
  130. a) Copy getRulebase.sample to getRulebase, and edit as follows:
  131. i) In the line
  132. AUTHENTICATION=authenticationxx
  133. replace authenticationxx with the authentication for the
  134. SNFServer license.
  135. ii) In the line
  136. LICENSE_ID=licenseid
  137. replace licenseid with the license ID of the SNFServer
  138. license.
  139. iii) Any other changes as necessary if the default directories
  140. are not used.
  141. b) Ensure that getRulebase is executable by the snfilter user.
  142. This can be done with the command:
  143. chmod +x getRulebase
  144. 5) Ensure that the snfilter user has read/write access to the files
  145. in workspace (default: /usr/share/snf-server or
  146. /usr/local/share/snf-server) and configuration directory (default:
  147. /etc/snf-server). To grant this access, enter the following command,
  148. as the root user:
  149. chown -R snfilter:snfilter /usr/share/snf-server
  150. chown -R snfilter:snfilter /etc/snf-server
  151. As you modify files in these directories, please ensure that the
  152. read/write permissions for snfilter is maintained.
  153. 4) Download the rulebase file:
  154. a) 'cd /usr/share/snf-server'. If the workspace specified in the
  155. configuration file is not the default, this command should be
  156. changed accordingly.
  157. b) 'touch UpdateReady.txt'.
  158. c) 'chown snfilter UpdateReady.txt'.
  159. d) 'su -m snfilter -c "/usr/sbin/getRulebase"'. If getRulebase
  160. is in a different directory, this command should be changed
  161. accordingly.
  162. OS-specific issues--
  163. None.
  164. Configuring the OS
  165. ******************
  166. The OS can be configured to automatically start and stop SNFServer on
  167. system startup and shutdown. The following gives the procedure for
  168. each OS:
  169. OpenBSD:
  170. 1) Add the following line to /etc/rc.local:
  171. /usr/local/sbin/snf-server start
  172. 2) Add the following line to /etc/rc.shutdown:
  173. /usr/local/sbin/snf-server stop
  174. 3) Run '/usr/local/sbin/snf-server start' to start the server.
  175. FreeBSD:
  176. 1) Create the directory /etc/rc.conf.d (if it doesn't exist).
  177. 2) Create the file /etc/rc.conf.d/snfsrver with the contents:
  178. snfserver_enable="YES"
  179. 3) Run '/usr/local/etc/rc.d/snf-server start' to start the server.
  180. Ubuntu:
  181. 1) Set the VERBOSE variable in /etc/default/rcS to control the
  182. script output.
  183. 2) Configure the system to run the script using the appropriate
  184. procedure.
  185. 3) Run '/etc/init.d/snf-server start' to start the server.
  186. RedHat (and variants such as Fedora) and Suse:
  187. 1) Run 'chkconfig --add snf-server'. This sonfigures the system to
  188. run the script on startup and shutdown.
  189. 2) Run 'chkconfig --list snf-server' to display the runlevels
  190. 3) Run 'service snf-server start' to start the SNFServer.
  191. Integration with MTAs
  192. *********************
  193. The section assumes you will be using SNFServer with an MTA and simply
  194. injecting headers that will be used later to remove, quarantine, or
  195. otherwise redirect messages detected as spam. There are as many ways
  196. to use SNFServer as there are systems using it -- so the following is
  197. just a good starting point.
  198. It is presumed that SNFServer is configured with x-header injection
  199. turned on and that the x-headers have been customized to suit your
  200. needs. Check the <xheaders/> section of your
  201. /etc/snf-server/SNFServer.xml file to verify that SNFServer is
  202. configured to do what you want.
  203. Integration with postfix
  204. ------------------------
  205. One way to integrate with postfix is to configure postfix to use the
  206. snfSniffer script (described below) as a content filter. The
  207. snfSniffer script passes the message through SNFServer, and then
  208. reinjects the message into the mail system.
  209. 1) In /usr/sbin (or /usr/local/sbin), copy the script
  210. snfSniffer.sample to snfSniffer set the correct access rights:
  211. cp snfSniffer.sample snfSniffer
  212. chown snfilter snfSniffer
  213. chmod 550 snfSniffer
  214. The default snfSniffer script creates a temporary copy of the message,
  215. scans it with SNFServer, and then reinjects the message.
  216. 2) Change /etc/postfix/master.cf as follows (LEADING WHITE SPACES
  217. ARE IMPORTANT WHEN MAKING THIS CHANGE):
  218. change (each line is enclosed in single quotes; add only the text
  219. between the single quotes):
  220. 'smtp inet n - n - - smtpd'
  221. to:
  222. 'smtp inet n - n - - smtpd'
  223. ' -o content_filter=snfilter:dummy'
  224. also add:
  225. 'snfilter unix - n n - 10 pipe'
  226. ' flags=Rq user=snfilter argv=/usr/sbin/snfSniffer'
  227. ' -f ${sender} -- ${recipient}'
  228. to master.cf. Specify the directory snfSniffer is in if not
  229. /usr/sbin.
  230. At this point you could just restart postfix, and hope nothing goes
  231. wrong. Instead, it would be smarter to first test the installation
  232. from the command line by injecting a message directly into the filter
  233. script "snfSniffer". We can issue a command like (in directory
  234. /usr/share/snf-server):
  235. /usr/sbin/snfSniffer -f sender recipient < junkmsg.txt
  236. Where junkmsg.txt is a spam test message. We should also test
  237. a clean message to make sure that this script is working as we
  238. expect it to. In this case we would issue a command like
  239. /usr/sbin/snfSniffer -f sender recipient < cleanmsg.txt
  240. If you've done everything correctly then all you have to do is reload
  241. postfix to start the content_filter working.
  242. 4) 'postfix reload'. Restart postfix.
  243. 5) To stop using the snfSniffer filter:
  244. i) Comment out or remove the '-o content_filter=snfilter:dummy'
  245. line in the /etc/postfix/master.cf file.
  246. ii) 'postsuper -r ALL' to remove content filter request records
  247. from existing queue files.
  248. iii) 'postfix reload' to reload the postfix configuration.
  249. OS-specific issues--
  250. 1) OpenBSD: In the default postfix configuration for OpenBSD, the
  251. postfix programs run chrooted in /var/spool/postfix. For that
  252. configuration, the /etc/pwd.db file needs to be made available to
  253. the postfix programs. This can be done by copying pwd.db:
  254. cp /etc/pwd.db /var/spool/postfix/etc
  255. If the /etc/pwd.db file is modified after copying, the postfix
  256. system issues a warning. To avoid this warning, copy the
  257. /etc/pwd.db file to /var/spool/postfix/etc directory whenever
  258. /etc/pwd.db is modified.
  259. Integration with sendmail
  260. -------------------------
  261. One way to integrate with send is to configure sendmail to use the
  262. snfSnifferFilter script (described below) as a filter. The snfSniffer
  263. script passes the message through SNFServer, and then sends the
  264. message to stdout. The integration is done by having sendmail use
  265. procmail to filter all mail (which is normally the default), and
  266. configuring procmail to use snfSnifferFilter as a filter.
  267. 1) In /usr/sbin (or /usr/local/sbin), copy the script
  268. snfSnifferFilter.sample to snfSnifferFilter set the correct access
  269. rights:
  270. cp snfSnifferFilter.sample snfSnifferFilter
  271. chown snfilter snfSnifferFilter
  272. chmod 550 snfSnifferFilter
  273. The default snfSnifferFilter script creates a temporary copy of the
  274. message, scans it with SNFServer, and then send the message to
  275. stdout.
  276. 2) Verify that sendmail is configured to use procmail to deliver
  277. mail. Please see the sendmail and procmail documentation for how
  278. to do this.
  279. 3) Create the file /etc/procmailrc (or whatever the system procmail
  280. rcfile is; see the procmail documentation for the path on your
  281. system) to contain the following lines:
  282. ':0 fw'
  283. '| /usr/sbin/snfSnifferFilter'
  284. where the single quotes are not to be included.
  285. At this point mail should be filtered by SNFServer. To check this,
  286. issue a command like (in directory /usr/share/snf-server):
  287. /usr/sbin/snfSnifferFilter < junkmsg.txt
  288. Where junkmsg.txt is a spam test message. We should also test a clean
  289. message to make sure that this script is working as we expect it to.
  290. In this case we would issue a command like
  291. /usr/sbin/snfSnifferFilter < cleanmsg.txt
  292. In either case you should see the message with the headers added by
  293. SNFServer.
  294. 4) To stop using the snfSnifferFilter:
  295. i) Comment out or remove the two lines you added to /etc/procmailrc.
  296. OS-specific issues--
  297. 1) OpenBSD: The default sendmail confiugration might not use
  298. procmail. To configure sendmail to use procmail, please ensure that
  299. procmail is installed and see the procmail documentation
  300. (/usr/local/share/examples/procmail/advanced) for the procedure to
  301. integrate procmail as an integrated local mail delivery agent.
  302. By default, procmail is installed in /usr/local/bin, and the system
  303. procmail rcfile is /etc/procmailrc.
  304. After you make the changes, stop sendmail with 'pkill sendmail', and
  305. start it with 'sendmail -bd'.
  306. 2) FreeBSD: The default sendmail confiugration might not use
  307. procmail. To configure sendmail to use procmail, please ensure that
  308. procmail is installed and see the procmail documentation
  309. (/usr/local/share/examples/procmail/advanced) for the procedure to
  310. integrate procmail as an integrated local mail delivery agent.
  311. By default, procmail is installed in /usr/local/bin, and the system
  312. procmail rcfile is /usr/local/etc/procmailrc.
  313. After you make the changes, restart sendmail with
  314. '/etc/rc.d/sendmail restart'.
  315. 3) RedHat, Fedora, Centos, Suse, and Ubuntu: Restart sendmail with
  316. '/etc/init.d/sendmail restart'.