readme.txt

   1 COMPILING\r
   2 ---------\r
   3 Compiling FMS requires CMake, Poco and iconv if you want to do charset\r
   4 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 If you want to use the bundled SQLite3 library, add a -D USE_BUNDLED_SQLITE=ON\r
  11 to the cmake command.  Use of the bundled SQLite3 library is on by default when\r
  12 compiling on a Mac.  To turn off charset conversion to UTF-8 when sending\r
  13 messages, add a -D DO_CHARSET_CONVERSION=OFF.  Compiling with charset\r
  14 conversion turned on is recommended.\r
  15 \r
  16 UPGRADING\r
  17 ---------\r
  18 It is always a good idea to make a copy of your current FMS installation before\r
  19 continuing.  First shut down FMS, make a copy of the directory, and then\r
  20 replace all files except the database with those from the new version.  You may\r
  21 keep the same database unless otherwise noted.\r
  22 \r
  23 INSTALLATION\r
  24 ------------\r
  25 Place the binary and any templates in a directory of your choice.  Windows\r
  26 users may need to download the runtime DLLs available from the fms Freesite and\r
  27 place in the fms directory if they are not already installed on the system.  On\r
  28 the first run, a database file will also be created in this directory.  Make\r
  29 sure the user that runs FMS has read/write access to this directory.\r
  30 \r
  31 RUNNING\r
  32 -------\r
  33 You may run FMS in console mode by running the binary directly.  If you are\r
  34 running *nix and would like to run as a daemon, use the --daemon argument.  On\r
  35 Windows, /registerService will install FMS as a service, and /unregisterService\r
  36 will uninstall the service.  Use the /displayName=name argument when installing\r
  37 the service to set the service name to whatever you want.  You will need to\r
  38 manually start the service unless you change the startup type in the service\r
  39 properties.\r
  40 \r
  41 EXITING\r
  42 -------\r
  43 To exit FMS running in console mode, press CTRL+C while at the console.  You\r
  44 can also use the shutdown button on the web interface to close FMS.  As a last\r
  45 resort, you may kill the process.\r
  46 \r
  47 WEB INTERFACE\r
  48 -------------\r
  49 By default, a web interface for administration will be running at http://\r
  50 localhost:8080.  You can use the interface to configure and administer FMS.\r
  51 \r
  52 NNTP CONFIGURATION\r
  53 ------------------\r
  54 By default, the NNTP server will listen on port 1119.  Configure your\r
  55 newsreader to connect to the machine running FMS on this port.  Use the web\r
  56 interface to create an identity and use the name of the identity as the\r
  57 username for the newsgroup account.  The email address may be anything, as it\r
  58 is discarded when posting messages.\r
  59 \r
  60 POSTING MESSAGES\r
  61 ----------------\r
  62 You must set your newsreader to use UTF-8 when posting messages.  Any non-text\r
  63 attachment to the message will be inserted as a regular file and the key added\r
  64 to the body of the message when received.  Keep the attachments small, as the\r
  65 message can't be inserted until all attachments are inserted.  Text attachments\r
  66 will be inlined with the message body.  Cross posting is fine, but remember\r
  67 that each identity can set a limit to the number of boards each message may be\r
  68 cross posted to.\r
  69 \r
  70 CONTROL BOARDS\r
  71 --------------\r
  72 Control boards are special boards that will add/remove trust from an identity.\r
  73 Create control boards in the web interface, and then reply to an identity's\r
  74 message to a control board to change the trust of the identity as per the\r
  75 settings for the board.  You may cross post to a regular board and a control\r
  76 board with the same message.  The control boards will be stripped from the\r
  77 message before inserting into Freenet.\r
  78 \r
  79 FREESITES\r
  80 ---------\r
  81 Each identity has the option to publish a freesite.  A generic HTML template\r
  82 called site-template.htm is used to insert the site.  You can customize the\r
  83 template by placing an HTML file called identityname-template.htm in the same\r
  84 directory as the fms binary.  In the template, the string [LINKS] will be\r
  85 replaced by a <ul> list of links and [CONTENT] will be replaced by the page\r
  86 content.  [IDENTITYNAME] will be replaced by the name of the identity inserting\r
  87 the Freesite.  The Freesite will be inserted once a day and contain your last\r
  88 10 posts and your trust list if you are publishing it.  The site will be\r
  89 inserted to a USK accessible via: USK@yourpublickey.../fms/0/\r
  90 \r
  91 You may add extra files to your Freesite by creating a file called identityname-\r
  92 files.txt that contains a list of files to add to the Freesite.  There should\r
  93 be one file per line, and the path to each file may be absolute or relative to\r
  94 the working directory, but you MUST use / as the path separator.  Files cannot\r
  95 be named index.htm, trustlist.htm, or files.htm.\r
  96 \r
  97 TRUST\r
  98 -----\r
  99 Trust is the most important element of FMS.  It determines which identities you\r
 100 will download messages from and thus your overall experience.  Do not give\r
 101 trust to arbitrary identities.  Pick whom you trust wisely.  The settings for\r
 102 minimum trust before downloading messages and trust lists can be changed on the\r
 103 web interface.\r
 104 \r
 105 You must have a local identity created before you can set trust levels.  Even\r
 106 if you don't want to post messages, you must still create an identity, but you\r
 107 do not have to announce it.  This way, no-one will know about that identity and\r
 108 you will be able to set trust.  If you have multiple identities, each with\r
 109 different trust levels for peers, the highest trust level set for a peer will\r
 110 determine if messages/trust lists are downloaded from them.\r
 111 \r
 112 A note on NULL trust:  If you neither trust or distrust an identity, they will\r
 113 have NULL trust (no trust at all).  You will download messages and trust lists\r
 114 from identities with NULL peer trust as long as the local trust level is at or\r
 115 above your configured minimum.  You will also download messages from identities\r
 116 with NULL local message trust (the peer message trust must be NULL or >= your\r
 117 configured minimum as well), but you will not download trust lists from\r
 118 identities with NULL local trust list trust.\r
 119 \r
 120 NNTP EXTENSIONS\r
 121 ---------------\r
 122 The following commands are available through the NNTP connection.  The client\r
 123 must have authenticated for the commands to work.  Comments MUST be surrounded\r
 124 by ".\r
 125 \r
 126 XSETTRUST MESSAGE userid@keypart val\r
 127 XSETTRUST TRUSTLIST userid@keypart val\r
 128 XSETTRUST MESSAGECOMMENT userid@keypart "comment"\r
 129 XSETTRUST TRUSTLISTCOMMENT userid@keypart "comment"\r
 130 \r
 131 Responses:\r
 132 2xx Trust Set\r
 133 4xx Unknown ID or other error\r
 134 5xx Syntax error\r
 135 \r
 136 XGETTRUST MESSAGE userid@keypart\r
 137 XGETTRUST TRUSTLIST userid@keypart\r
 138 XGETTRUST PEERMESSAGE userid@keypart\r
 139 XGETTRUST PEERTRUSTLIST userid@keypart\r
 140 \r
 141 Responses:\r
 142 2xx val\r
 143 4xx Unknown ID or other error\r
 144 5xx Syntax error\r
 145 \r
 146 XGETTRUSTLIST\r
 147 trust values will be 0 to 100 or can be the string "null" without quotes.\r
 148 \r
 149 Responses:\r
 150 2xx Trust List Follows\r
 151 userid@keypart TAB messagetrust TAB trustlisttrust TAB peermessagetrust TAB peertrustlisttrust TAB messagecomment TAB trustlistcomment\r
 152 .\r
 153 4xx other error\r