readme.txt

   1 COMPILING\r
   2 ---------\r
   3 Compiling FMS requires CMake, Poco ( version >=1.2.9 ) and iconv if you want to\r
   4 do charset conversion.  Other required libraries are bundled with FMS.\r
   5 \r
   6 To compile, run these commands from the source directory:\r
   7 cmake -D I_HAVE_READ_THE_README=ON .\r
   8 make\r
   9 \r
  10 Compiling with the bundled SQLite library is on by default.  If you do not want\r
  11 to use the bundled SQLite library, add a -D USE_BUNDLED_SQLITE=OFF to the cmake\r
  12 command.  To turn off charset conversion to UTF-8 when sending messages, add a\r
  13 -D DO_CHARSET_CONVERSION=OFF.  Compiling with charset conversion turned on is\r
  14 recommended.  If you would like to compile using the alternate captchas, add a\r
  15 -D ALTERNATE_CAPTCHA=ON to the cmake command line. This option requires the\r
  16 FreeImage library to be installed.\r
  17 \r
  18 Query logging may be turned on by adding a -D QUERY_LOG=ON.  This will create a\r
  19 file called query.log in the working directory.  Straight SQL statements will\r
  20 be captured, as well as the setup of prepared statements.  Each step through a\r
  21 prepared statement is also logged, but the details are not, so there should be\r
  22 no sensitive information in this log file.\r
  23 \r
  24 UPGRADING\r
  25 ---------\r
  26 *ALWAYS* make a copy of your current FMS installation before continuing.  First\r
  27 shut down FMS, make a copy of the directory, and then replace all files except\r
  28 the database with those from the new version.  You may keep the same database\r
  29 unless otherwise noted in the release information.\r
  30 \r
  31 INSTALLATION\r
  32 ------------\r
  33 Place the binary, any templates, and the fonts and images directories in a\r
  34 directory of your choice.  Windows users may need to download the runtime DLLs\r
  35 available from the fms Freesite and place in the fms directory if they are not\r
  36 already installed on the system.  On the first run, a database file will also\r
  37 be created in this directory.  Make sure the user that runs FMS has read/write\r
  38 access to this directory.\r
  39 \r
  40 RUNNING\r
  41 -------\r
  42 You may run FMS in console mode by running the binary directly.  You can view\r
  43 available command line options by typing /help on Windows and --help on other\r
  44 platforms.  If you are running *nix and would like to run as a daemon, use the \r
  45 --daemon argument.  On Windows, /registerService will install FMS as a service,\r
  46 and /unregisterService will uninstall the service.  Use the /displayName=name\r
  47 argument when installing the service to set the service name to whatever you\r
  48 want.  You will need to manually start the service unless you change the\r
  49 startup type in the service properties.\r
  50 \r
  51 FMS must run a good portion of the day every day to work properly.  The slower\r
  52 your Freenet connection is, the longer FMS must be run to find the\r
  53 communications of other identities.  You will not have a good experience only\r
  54 running FMS a few hours a day.\r
  55 \r
  56 If you are experiencing a problem with FMS that you can't solve, and you've\r
  57 already rebooted your machine, restarted FMS, and have reproduced the problem\r
  58 with a brand new database, follow these instructions.  Set the logging option\r
  59 to trace and restart FMS.  Create a post on the fms group with a descriptive\r
  60 subject and a body that contains the operating system you are using, along with\r
  61 a description of the problem, what you have tried already, if you are using a\r
  62 precompiled binary, the startup lines from the log file as well as the portion\r
  63 that corresponds to the problem you are experiencing, and any other information\r
  64 you have that pertains to the problem.  Make sure to anonymize any IP addresses,\r
  65 host names, subnet masks, and keys from the log that you don't want people to\r
  66 know about.\r
  67 \r
  68 EXITING\r
  69 -------\r
  70 To exit FMS running in console mode, press CTRL+C while at the console.  You\r
  71 can also use the shutdown button on the web interface to close FMS.  As a last\r
  72 resort, you may kill the process.\r
  73 \r
  74 WEB INTERFACE\r
  75 -------------\r
  76 By default, a web interface for administration will be running at http://\r
  77 localhost:8080.  You can use the interface to configure and administer FMS.\r
  78 There is also a forum built into the web interface so you can read and send\r
  79 messages without needing to use a newsreader.\r
  80 \r
  81 NNTP CONFIGURATION\r
  82 ------------------\r
  83 By default, the NNTP server will listen on port 1119.  Configure your\r
  84 newsreader to connect to the machine running FMS on this port.  Use the web\r
  85 interface to create an identity and use the name of the identity as the\r
  86 username for the newsgroup account.  The email address may be anything, as it\r
  87 is discarded when posting messages.\r
  88 \r
  89 POSTING MESSAGES\r
  90 ----------------\r
  91 You must set your newsreader to use UTF-8 when posting messages unless you have\r
  92 compiled with charset conversion turned on.  All headers of the message that\r
  93 aren't needed will be stripped and all headers necessary for the proper sending\r
  94 of the message will be replaced with sanitized ones.  Any non-text attachment\r
  95 to the message will be inserted as a regular file and the key added to the body\r
  96 of the message when received.  Keep the attachments small, as the message can't\r
  97 be inserted until all attachments are inserted.  Text attachments will be\r
  98 inlined with the message body.  Cross posting is fine, but remember that each\r
  99 identity can set a limit to the number of boards each message may be cross\r
 100 posted to.\r
 101 \r
 102 CONTROL BOARDS\r
 103 --------------\r
 104 Control boards are special boards that will add/remove trust from an identity.\r
 105 Create control boards in the web interface, and then reply to an identity's\r
 106 message to a control board to change the trust of the identity as per the\r
 107 settings for the board.  You may cross post to a regular board and a control\r
 108 board with the same message.  The control boards will be stripped from the\r
 109 message before inserting into Freenet.\r
 110 \r
 111 FREESITES\r
 112 ---------\r
 113 Each identity has the option to publish a freesite.  A generic HTML template\r
 114 called site-template.htm is used to insert the site.  You can customize the\r
 115 template by placing an HTML file called identityname-template.htm in the same\r
 116 directory as the fms binary.  In the template, the string [LINKS] will be\r
 117 replaced by a <ul> list of links and [CONTENT] will be replaced by the page\r
 118 content.  [IDENTITYNAME] will be replaced by the name of the identity inserting\r
 119 the Freesite.  The Freesite will be inserted once a day and contain your last\r
 120 10 posts and your trust list if you are publishing it.  The site will be\r
 121 inserted to a USK accessible via: USK@yourpublickey.../fms/0/\r
 122 \r
 123 You may add extra files to your Freesite by creating a file called identityname-\r
 124 files.txt that contains a list of files to add to the Freesite.  There should\r
 125 be one file per line, and the path to each file may be absolute or relative to\r
 126 the working directory, but you MUST use / as the path separator.  Files cannot\r
 127 be named index.htm, trustlist.htm, or files.htm.\r
 128 \r
 129 TRUST\r
 130 -----\r
 131 Trust is the most important element of FMS.  It determines which identities you\r
 132 will download messages from and thus your overall experience.  Do not give\r
 133 trust to arbitrary identities.  Pick whom you trust wisely.  The settings for\r
 134 minimum trust before downloading messages and trust lists can be changed on the\r
 135 web interface.\r
 136 \r
 137 You must have a local identity created before you can set trust levels.  Even\r
 138 if you don't want to post messages, you must still create an identity, but you\r
 139 do not have to announce it.  This way, no-one will know about that identity and\r
 140 you will be able to set trust.  If you have multiple identities, each with\r
 141 different trust levels for peers, the highest trust level set for a peer will\r
 142 determine if messages/trust lists are downloaded from them.\r
 143 \r
 144 A note on NULL trust:  If you neither trust or distrust an identity, they will\r
 145 have NULL trust (no trust at all).  You will download messages and trust lists\r
 146 from identities with NULL peer trust as long as the local trust level is at or\r
 147 above your configured minimum.  You will also download messages from identities\r
 148 with NULL local message trust (the peer message trust must be NULL or >= your\r
 149 configured minimum as well), but you will not download trust lists from\r
 150 identities with NULL local trust list trust.\r
 151 \r
 152 NNTP EXTENSIONS\r
 153 ---------------\r
 154 The following commands are available through the NNTP connection.  The client\r
 155 must have authenticated for the commands to work.  Comments MUST be surrounded\r
 156 by ".\r
 157 \r
 158 XSETTRUST MESSAGE userid@keypart val\r
 159 XSETTRUST TRUSTLIST userid@keypart val\r
 160 XSETTRUST MESSAGECOMMENT userid@keypart "comment"\r
 161 XSETTRUST TRUSTLISTCOMMENT userid@keypart "comment"\r
 162 \r
 163 Responses:\r
 164 2xx Trust Set\r
 165 4xx Unknown ID or other error\r
 166 5xx Syntax error\r
 167 \r
 168 XGETTRUST MESSAGE userid@keypart\r
 169 XGETTRUST TRUSTLIST userid@keypart\r
 170 XGETTRUST PEERMESSAGE userid@keypart\r
 171 XGETTRUST PEERTRUSTLIST userid@keypart\r
 172 \r
 173 Responses:\r
 174 2xx val\r
 175 4xx Unknown ID or other error\r
 176 5xx Syntax error\r
 177 \r
 178 XGETTRUSTLIST\r
 179 trust values will be 0 to 100 or can be the string "null" without quotes.\r
 180 \r
 181 Responses:\r
 182 2xx Trust List Follows\r
 183 userid@keypart TAB messagetrust TAB trustlisttrust TAB peermessagetrust TAB peertrustlisttrust TAB messagecomment TAB trustlistcomment\r
 184 .\r
 185 4xx other error\r