COMPILING\r
---------\r
-Compiling FMS requires CMake, and pthreads. Other required libraries are\r
-bundled with FMS.\r
+Compiling FMS requires CMake, Poco ( version >=1.2.9 ) and iconv if you want to\r
+do charset conversion. Other required libraries are bundled with FMS.\r
\r
To compile, run these commands from the source directory:\r
-cmake .\r
+cmake -D I_HAVE_READ_THE_README=ON .\r
make\r
\r
-If you want to use the bundled SQLite3 library, add a -D USE_BUNDLED_SQLITE=ON\r
-to the cmake command.\r
+Compiling with the bundled SQLite library is on by default. If you do not want\r
+to use the bundled SQLite library, add a -D USE_BUNDLED_SQLITE=OFF to the cmake\r
+command. To turn off charset conversion to UTF-8 when sending messages, add a\r
+-D DO_CHARSET_CONVERSION=OFF. Compiling with charset conversion turned on is\r
+recommended. If you would like to compile using the alternate captchas, add a\r
+-D ALTERNATE_CAPTCHA=ON to the cmake command line. This option requires the\r
+FreeImage library to be installed.\r
+\r
+Query logging may be turned on by adding a -D QUERY_LOG=ON. This will create a\r
+file called query.log in the working directory. Straight SQL statements will\r
+be captured, as well as the setup of prepared statements. Each step through a\r
+prepared statement is also logged, but the details are not, so there should be\r
+no sensitive information in this log file.\r
\r
UPGRADING\r
---------\r
-It is always a good idea to make copies of your current FMS installation before\r
-continuing. First shut down FMS and then replace the binary and template.htm\r
-with those from the new version. You may keep the same database unless\r
-otherwise noted.\r
+*ALWAYS* make a copy of your current FMS installation before continuing. First\r
+shut down FMS, make a copy of the directory, and then replace all files except\r
+the database with those from the new version. You may keep the same database\r
+unless otherwise noted in the release information.\r
\r
INSTALLATION\r
------------\r
-Place the binary and template.htm in a directory of your choice. On the first\r
-run, a database file will also be created in this directory. Make sure the\r
-user that runs FMS has read/write access to this directory.\r
+Place the binary, any templates, and the fonts and images directories in a\r
+directory of your choice. Windows users may need to download the runtime DLLs\r
+available from the fms Freesite and place in the fms directory if they are not\r
+already installed on the system. On the first run, a database file will also\r
+be created in this directory. Make sure the user that runs FMS has read/write\r
+access to this directory.\r
\r
RUNNING\r
-------\r
-You may run FMS in console mode by running the binary directly. If you are\r
-running *nix and would like to run as a daemon, use the -d argument. On\r
-Windows, -i will install FMS as a service, and -u will uninstall the service.\r
+You may run FMS in console mode by running the binary directly. You can view\r
+available command line options by typing /help on Windows and --help on other\r
+platforms. If you are running *nix and would like to run as a daemon, use the \r
+--daemon argument. On Windows, /registerService will install FMS as a service,\r
+and /unregisterService will uninstall the service. Use the /displayName=name\r
+argument when installing the service to set the service name to whatever you\r
+want. You will need to manually start the service unless you change the\r
+startup type in the service properties.\r
+\r
+FMS must run a good portion of the day every day to work properly. The slower\r
+your Freenet connection is, the longer FMS must be run to find the\r
+communications of other identities. You will not have a good experience only\r
+running FMS a few hours a day.\r
+\r
+If you are experiencing a problem with FMS that you can't solve, and you've\r
+already rebooted your machine, restarted FMS, and have reproduced the problem\r
+with a brand new database, follow these instructions. Set the logging option\r
+to trace and restart FMS. Create a post on the fms group with a descriptive\r
+subject and a body that contains the operating system you are using, along with\r
+a description of the problem, what you have tried already, if you are using a\r
+precompiled binary, the startup lines from the log file as well as the portion\r
+that corresponds to the problem you are experiencing, and any other information\r
+you have that pertains to the problem. Make sure to anonymize any IP addresses,\r
+host names, subnet masks, and keys from the log that you don't want people to\r
+know about.\r
\r
EXITING\r
-------\r
-------------\r
By default, a web interface for administration will be running at http://\r
localhost:8080. You can use the interface to configure and administer FMS.\r
+There is also a forum built into the web interface so you can read and send\r
+messages without needing to use a newsreader.\r
\r
NNTP CONFIGURATION\r
------------------\r
username for the newsgroup account. The email address may be anything, as it\r
is discarded when posting messages.\r
\r
-Posting Messages\r
+POSTING MESSAGES\r
----------------\r
-Use must set your newsreader to use UTF-8 when posting messages. Any non-text\r
-attachment to the message will be stripped. Text attachments will be inlined\r
-with the message body. Cross posting is fine, but remember that each identity\r
-can set a limit to the number of boards each message may be cross posted to.\r
+You must set your newsreader to use UTF-8 when posting messages unless you have\r
+compiled with charset conversion turned on. All headers of the message that\r
+aren't needed will be stripped and all headers necessary for the proper sending\r
+of the message will be replaced with sanitized ones. Any non-text attachment\r
+to the message will be inserted as a regular file and the key added to the body\r
+of the message when received. Keep the attachments small, as the message can't\r
+be inserted until all attachments are inserted. Text attachments will be\r
+inlined with the message body. Cross posting is fine, but remember that each\r
+identity can set a limit to the number of boards each message may be cross\r
+posted to.\r
\r
CONTROL BOARDS\r
--------------\r
board with the same message. The control boards will be stripped from the\r
message before inserting into Freenet.\r
\r
+FREESITES\r
+---------\r
+Each identity has the option to publish a freesite. A generic HTML template\r
+called site-template.htm is used to insert the site. You can customize the\r
+template by placing an HTML file called identityname-template.htm in the same\r
+directory as the fms binary. In the template, the string [LINKS] will be\r
+replaced by a <ul> list of links and [CONTENT] will be replaced by the page\r
+content. [IDENTITYNAME] will be replaced by the name of the identity inserting\r
+the Freesite. The Freesite will be inserted once a day and contain your last\r
+10 posts and your trust list if you are publishing it. The site will be\r
+inserted to a USK accessible via: USK@yourpublickey.../fms/0/\r
+\r
+You may add extra files to your Freesite by creating a file called identityname-\r
+files.txt that contains a list of files to add to the Freesite. There should\r
+be one file per line, and the path to each file may be absolute or relative to\r
+the working directory, but you MUST use / as the path separator. Files cannot\r
+be named index.htm, trustlist.htm, or files.htm.\r
+\r
TRUST\r
-----\r
Trust is the most important element of FMS. It determines which identities you\r
will download messages from and thus your overall experience. Do not give\r
-trust to arbitrary identities. Pick whom you trust wisely. There settings for\r
+trust to arbitrary identities. Pick whom you trust wisely. The settings for\r
minimum trust before downloading messages and trust lists can be changed on the\r
web interface.\r
\r
+You must have a local identity created before you can set trust levels. Even\r
+if you don't want to post messages, you must still create an identity, but you\r
+do not have to announce it. This way, no-one will know about that identity and\r
+you will be able to set trust. If you have multiple identities, each with\r
+different trust levels for peers, the highest trust level set for a peer will\r
+determine if messages/trust lists are downloaded from them.\r
+\r
A note on NULL trust: If you neither trust or distrust an identity, they will\r
have NULL trust (no trust at all). You will download messages and trust lists\r
-from identities with NULL peer trust as long as the local trust level is above\r
-your configured minimum. You will also download messages from identities with\r
-NULL local message trust (the peer message trust must be NULL or > your\r
+from identities with NULL peer trust as long as the local trust level is at or\r
+above your configured minimum. You will also download messages from identities\r
+with NULL local message trust (the peer message trust must be NULL or >= your\r
configured minimum as well), but you will not download trust lists from\r
identities with NULL local trust list trust.\r
+\r
+NNTP EXTENSIONS\r
+---------------\r
+The following commands are available through the NNTP connection. The client\r
+must have authenticated for the commands to work. Comments MUST be surrounded\r
+by ".\r
+\r
+XSETTRUST MESSAGE userid@keypart val\r
+XSETTRUST TRUSTLIST userid@keypart val\r
+XSETTRUST MESSAGECOMMENT userid@keypart "comment"\r
+XSETTRUST TRUSTLISTCOMMENT userid@keypart "comment"\r
+\r
+Responses:\r
+2xx Trust Set\r
+4xx Unknown ID or other error\r
+5xx Syntax error\r
+\r
+XGETTRUST MESSAGE userid@keypart\r
+XGETTRUST TRUSTLIST userid@keypart\r
+XGETTRUST PEERMESSAGE userid@keypart\r
+XGETTRUST PEERTRUSTLIST userid@keypart\r
+\r
+Responses:\r
+2xx val\r
+4xx Unknown ID or other error\r
+5xx Syntax error\r
+\r
+XGETTRUSTLIST\r
+trust values will be 0 to 100 or can be the string "null" without quotes.\r
+\r
+Responses:\r
+2xx Trust List Follows\r
+userid@keypart TAB messagetrust TAB trustlisttrust TAB peermessagetrust TAB peertrustlisttrust TAB messagecomment TAB trustlistcomment\r
+.\r
+4xx other error\r
projects / fms.git / blobdiff