.. -*- rst -*- ======== BoreWiki ======== ---- (Readme for version 0.971, third public release to see if there is interested outsite author's home use for this. Doc incomplete and outlook a bit harsh but nevertheless quite useful). ---- .. contents:: BoreWiki is a wiki with following features: #. Uses reStructuredText_ for markup (or for no markup). #. Saves old versions of pages (in an RCS files). #. Has better-than-nothing user authentication with better-than-plaintext passwords. #. Creates static web pages for normal viewing. .. _reStructuredText: http://docutils.sourceforge.net/rst.html BoreWiki is mostly written in perl, using perl reStructuredText module via its command line interface called prest. Prest can be (currently) found by the following Google__ search. Prest is currently included in a stripped form for exploration purposes; this probably changes in the future. See Makefile target ``bwprest`` for information about the stripping process. __ http://www.google.com/search?q=text-restructured License ------- BoreWiki is licenced under GPL v2. Prest code is licenced under the Perl license. For more information of Prest license see ``COPYING.txt`` in prest subdirectory. Security Notes -------------- BoreWiki uses it's own password scheme (md5 hash and simple salt). It's security is not confirmed in any way, but it is better than plaintext passwords. And since in many cases the password is sent plaintext over the network the password can be figured out there. As the password scheme is not compatible with anything else one cannot mix hashed passwords with other system, thus compromising those if there were security problem here. The perl code I've written here is quite well checked out for attacks via cgi interface (thanks perl taint checks!) and I trust the Text-Restructured code is quite good in this area. However I cannot quarantee any of this so use this code carefully and remember to monitor logs often enough. So, NO WARRANTY, entire risk of using this program is with you. Quick start ----------- If you are using modern Linux system, the following few steps might be enough to get this running. If not, see `Installation Issues`_ :: $ make install cd=$HOME/.borewiki dd=$HOME/public_html $ cd $HOME/public_html $ ./borewiki-admin newuser tuser TestUser / Now start web browser and enter ``127.0.0.1/~/BoreWiki.cgi?TestPage`` to the address bar. Replace 127.0.0.1 and with real info... User-visible functionality -------------------------- To begin editing of BoreWiki-managed web page (after bootstrapping) user usually loads BoreWiki.cgi via Redirection using borewiki-generated page.htm file (By removing final `l` from the URL on the address bar). If user has not authenticated yet (or cookie has expired) instead of loading page edit page user will be shown authentication dialog. After successful authentication user is instructed to go back to the authentication dialog page and **reload** that page. Now, if user has access permission to edit the page, page edit page will appear, otherwise simple *Permission Denied* text will be shown. Content written to the textwiew on a edit web page will be passed unmodified to reStructuredText parser that generates [x]html output out of it. At this preview stage BoreWiki-provided xhtml postprocessor filter adds tag to the page (to make relative hyperlinks point to the right files) and adds some BoreWiki information to the page footer. The preview page shows how the page will look out after save button is pressed. If it does not look OK, user can just go **back** one page and continue editing content. At this time `View Document Source`__ link does not work (as it does here) and Relative links to .html-suffixed pages that user may edit (remember access control) but does not exist yet will not work. After page is **saved** the postprocessor filter will create *stub pages* for these pages (assumed all checks will succeed, notably the one that directory for new page needs to exist, BoreWiki will not create new pages, system user needs to do that step on CLI shell using ``borewiki-admin.sh mkdir`` (or just simple ``mkdir``)). .. __: Readme BoreWiki supports concurrent editing simply running ``merge(1)`` command if it notices someone else has committed changes over the same revision user started to edit with. User will be informed if such merge has taken place so that the user remembers to investigate final results more carefully and fix in a re-edit phase any weirdness that came out. After **save** is complete user is instructed to go back three (3) pages, back to the .html page user started to work on (in usual use case, anyway). Installation Issues ------------------- Things may work good or bad after the above quick start. The following things may help/improve the current situation. - Other (unix) systems randombytes() needs tuning (in BoreWiki.cgi and in borewiki-admin.sh). what else... - http config Stuff for apache httpd.conf: ``AddHandler cgi-script .cgi`` ``#Userdir disable`` ``UserDir public_html`` Add ``Options ... ExecCGI`` to ```` - selinux If your system uses selinux, and things don't work, you can try ``chcon -R -t httpd_sys_content_t $HOME/public_html`` and ``chcon system_u:object_r:httpd_sys_script_exec_t $HOME/public_html/BoreWiki.cgi``. That did not help for me, so I entered: ``su -c 'setenforce 0'`` - Directory/file permissions If things fail because of this, move stuff elsewhere. - UTF-8 output in -htaccess Add ``AddCharset UTF-8 .html .rst`` to .htaccess if required... Functionality Notes ------------------- Some notes how things are implemented, for now. - Run borewiki-admin.sh without any args to get it's command list. Every command that requires command line arguments will print more detailed usage information of command's functionality. More docs will follow when is it written (by someone). - /passwd.conf will contain password information. Entries are added by using borewiki-admin.sh tool. This file is version controlled. borewiki-admin.sh has also command to delete some old revision of password file (delpwrev). - /cookies.conf contains cookies for authenticated users. cookies will expire when browser is shut down, or after 5 hours. - temporary rst files are stored when preview button is pressed. Save option uses that file to be saved. Going back to re-edit the will re-use the same temp file (unless edit is reloaded). If save is never clicked this temporary rst file will expire after 86400 seconds (24 hours, one day). - Edit page is loaded using GET method. The only argument allowed if (non-suffix) path to the page to be edited. All other requests (preview, save) uses POST method and ignores anything on address line. - Dummy page with edit instructions are added for each link that is added to a page and references directory space where user has access. - Lotsa mode, TBD. .. FAQ .. --- --- ToDo for version 1.0 -------------------- * Nicer documentation, perhaps some initial page(s) to start with. (initial pages will be in separate .tar.gz file with instructions how to install those from command line (gtar -C ... -kzxvf demopages.tar.gz)). * Code audit, check through BoreWiki.cgi and then prest code. ToDo ---- (in no particular order) * More docs * Some code cleanup * Some cgi web output tunes