-------------------------------------------- WIKIC README by Pieter Suurmond, feb 9, 2005 -------------------------------------------- 0: CONTENTS =========== 1) License. 2) Motivation and objectives. 3) Configuration. 4) Compilation, installation and starting up. 5) Security issues. 6) On-the-fly document conversion (ABC to PostScript and MIDI). 7) Dependancies. 8) Directory structure. 9) Bugs. 10) Thanks. 1: LICENSE ========== WikiC version 2.05, feb 9, 2004. Latest sourcecode available at http://www.hku.nl/~pieter/SOFT/CGI/ Copyright (c) 2003 2004 2005 Pieter Suurmond Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. Any person wishing to distribute modifications to the Software is requested to send the modifications to the original developer so that they can be incorporated into the canonical version. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. 2: MOTIVATION AND OBJECTIVES ============================ Clean, memorizable URLs. Simple and short queries. In determining MIME types, the file-suffix following the LAST occurence of a period is used (rather than the FIRST, as Apache sometimes does). When a .cgi program serves a PDF file, for instance, and a client wants to save it to disk, the browser may suggest "save as xxx.cgi". I want to get rid of this nasty behaviour. Also, using '/cgi-bin/', '.cgi' and '?-queries' overcomplicates things. Nice exercise in multithreaded socket programming and writing parsers in C. 3: CONFIGURATION ================ Before compiling, the following two files may need inspection: 1) Makefile 2) wikic_config.c First walk through the makefile and decide whether you want optional features (LDAP, ABC and PDF). When attempting to compile this software for the first time, better leave all optional features in the Makefile as they are: OFF BY DEFAULT. The only important thing you may possibly want to edit in the Makefile is the selected compiler: 'cc', 'gcc' or any other. You can walk then through the C-language configuration file in 3 or 4 steps, just skip the optional features that you did not enable in the Makefile. There are two levels of configuration, static and dynamic. STATIC CONFIGURATION -------------------- Static configurations and default settings are defined in sourcefile 'wikic_config.c'. (They may be overruled by things in the Makefile!) Changing things here, almost always requires recompilation. *) Choose server name: In 'wikic_config.c', string 'gd.software' may be set to some name. *) Choose port number: In 'wikic_config.c', integer 'gd.port' selects the port to bind to. 8080 is the default because that requires no root access. Now, when a port number below 1024 is choosen, wikic will attempt to drop privileges (to the user- and group-ID taken from the current directory) after opening and binding to a socket on the given low port. To effectively startup the server you need to be superuser. When you do su before starting up wikic, take care PATH is still ok. I ob- served the following, before and after su on IRIX: user: PATH=/usr/sbin:/usr/bsd:/sbin:/usr/bin:/usr/bin/X11:/usr/freeware/bin root: PATH=/usr/sbin:/usr/bsd:/sbin:/usr/bin:/etc:/usr/etc:/usr/bin/X11 So if necessary, type: setenv PATH /usr/sbin:/usr/bsd:/sbin:/usr/bin:/etc:/usr/etc:/usr/bin/X11:/usr/freeware/bin Because otherwise, Ghostscript might not work correctly! *) Choose ps to pdf utility: In 'wikic_config.c', string 'gd.ps2pdf_path' selects the PostScript to PDF utility to use. Make it NULL or "" to disable this feature. *) Choose C compiler: In the the 'makefile', you may, for instance, alter 'gcc' to 'cc'. DYNAMIC CONFIGURATION --------------------- Dynamic configurations can be altered at runtime via webinterface /admin/. This requires no recompilation. The defaults of these dynamic parameters, however, can be set in source/wikic_config.c. 4: COMPILING, INSTALLING AND STARTING UP WIKIC ============================================== Go to the subdirectory called 'source' by typing cd source Then try to compile the sourcecode by typing make which should yield 3 exectables. Don't panic when the second or third executable fails to compile ('ldap_wikic_bind' is only for external LDAP-authentication; 'abc2ps' is only to support serverside ABC to PostScript conversion). Now move all executables (or at least 'wikic') to the parent directory by typing make install (Notice SGI IRIX users may prefer 'gmake' and 'gmake inst' instead.) Besides C executables, 'make inst' also copies 2 shell scripts to the parent directory, they can be used for startup and closedown. Now change one directory level up again by typing cd .. Finally start up the wikiserver by typing ./wikic & Take a look in a webbrowser at location 'http://localhost:8080' and one should see the wikiserver up and running. When you use the supplied usersfile, you can now login with username 'root' and password also 'root'. In case port 8080 is not available for the wikiserver, choose another port by editting sourcefile 'source/wikic_config.c' and repeat all above steps. Standard output of the UNIX program may be accumulated in a file (rather than displayed on the terminal) by starting up with something like: ./wikic>wikic_out & With the 'wikicctl' tool (which resembles 'apachectl') you can start and stop the server. When stopping the server, it sends a USR1 signal to the wikic program (extracting the process number from the PID file) and it should gracefully shutdown, deleting the PID file it created itself. ./wikicctl start ./wikicctl stop 5: SECURITY ISSUES ================== When distributing your own wiki code, take care NOT to publish the following two private files: 1) users 2) source/wikic_config.c Instead, distribute the files called 'users.dist' and 'source/wikic_config.c.dist' as example files. The encryption algorithm used in the cookies is very naive, and thus easy to crack! When you don't trust this, install some of the more robust encryption packages (that are freely available). The usersfile may contain raw, not encrypted passwords. Furthermore, nothing can be guarenteed (see license), there could be security holes anywhere, hidden in the C code. Since this is an experimental program, it should not be run with root privileges. When one has Apache running on a machine at port 80, one may configure proxies to redirect traffic to the wikic program, running on the same machine, at port 8080 for instance. This seems the safest way to run wikic on port 80 (avoiding risky setuid() and setguid() calls). Nevertheless, I started it up as 'root' and it keeps running for months on an Indy... :-) it is a bit 'dangerous' though... 6: ON-THE-FLY DOCUMENT CONVERSION ================================= Below are some notes about the integration of the abc2ps and abc2midi programs in the wikiserver. The abc2ps program is kept external and is called by the server when a client requests a certain (revision of an) abc file to be converted to PostScript format. The PostScript output is generated on-the-fly, it is not cached or stored permanently on the wikiserver. We need a unique way to request for conversion, to distinguish from really stored PostScript files under /wiki/ and /raw/. We do so by substituting /wiki/ or /raw/ by /convert/. Normal documents are viewable in both raw and text-embedded form (they can be accessed via /raw/ and /wiki/ respectively). This is not the case with on-the-fly converted documents, they can only be accessed through /convert/ and they default to raw. The URL (GET-request) explicitly reveals the request of a non- existing document, it must be converted on-the-fly. The revision number is maintained in the new URL. For example, when the third revision (#2) of an abc-document has to be translated into a PostScript file: /wiki/Praeludium_II.abc?2 will shows a hyperlink for conversion from ABC to PostScript, on the bottom of the page: /convert/Praeludium_II.abc.ps?2 Some conversions involve a 2-stage process. For example: ABC to PDF requires an intermediate PostScript file. The URL, however, does not show that it involves a 2-stage conversion. For example, use a request like /convert/Praeludium_II.abc.pdf?2 instead of /convert/Praeludium_II.abc.ps.pdf?2 It is not possible to edit or upload files under /convert/. 7: DEPENDANCIES =============== At minimum, WikiC requires the following: 1) A UNIX system. Many UNIX specific C headers are needed by the software. 2) POSIX threads and locks. The pthread library and header must be installed. 3) POSIX software signal facilities (sigaction(), sigcontext_t and such via ). 4) Standard C compiler to compile the sourcecode. For example GCC. Optional features: 4) Connecting to an LDAP server is supported to provide an alternative way of authentication (besides the local pass wordfile). To compile the two LDAP tools, you need the and headers installed. In subdirectory source you 'll find the compressed package: openldap-2.0.23.tar.gz. 5) Ghostscript ('gs' + 'ps2pdf') must be installed to convert PostScript documents to PDF. When you have no 'ps2pdf'-tool, or when you don't want to allow this feature, set 'ps2pdf_path' to NULL in sourcefile wikic_config.c. (Notice that SGI IRIX user may need to extend their environment variable 'PATH' with '/usr/freeware/bin' if 'gs' is installed there because the 'ps2pdf' script is just a wrapper around 'gs' and thus needs to find it.) Abc2ps software, which is also available under GNU license, is embedded in wikiC, rather than expected to be installed somewhere on the system. The reasons for this are: fine-tuning of abc2pc and reducing dependancies. 8: DIRECTORY STRUCTURE ====================== The toplevel directory, where this README resides, is the execution directory. The main executable 'wikic' and most of it's tools sit here. Before compilation and running, the toplevel directory should look something like this: 24 -rw------- 1 pieter user 11558 Nov 16 16:39 README 0 drwx------ 2 pieter user 9 Nov 9 08:16 search 8 drwx------ 4 pieter user 4096 Nov 16 16:46 source 8 -rw------- 1 pieter user 843 Nov 16 06:32 users 8 -rw------- 1 pieter user 184 Apr 23 2003 users.dist 8 drwx------ 49 pieter user 4096 Nov 16 06:33 wiki 8 drwx------ 49 pieter user 4096 Nov 16 06:33 trash After a successfull 'make' and subsequent 'make inst', the following executables are added: 656 -rwx------ 1 pieter user 331824 Nov 16 16:46 abc2ps 72 -rwx------ 1 pieter user 36812 Nov 16 16:46 ldap_mail_search 56 -rwx------ 1 pieter user 28416 Nov 16 16:46 ldap_simple_bind 304 -rwx------ 1 pieter user 152344 Nov 16 16:46 wikic 8 -rwx------ 1 pieter user 1457 Nov 7 12:03 wikicctl During running, some data files may be created: 8 -rw------- 1 pieter user 7 Nov 16 17:02 PID 32 -rw------- 1 pieter user 14177 Nov 4 01:22 recentEdits 8 -rw------- 1 pieter user 98 Nov 16 17:02 wikic.log The PID file will be removed by wikic when it shuts down gracefully. The toplevel directory itself, as well as all its' contents may be given very restrictive access permissions because only one user has to access files and subdirectories. You may want to type some chmod commands: chmod og-rwx * When you make the parenting directory (the executable directory) owned by 'sys' or 'root', wikic is aware of not really downgrading (at startup!) and should quit immediately. 9: BUGS ======= Many. Destructive parsing of the initial request from the client. Allocating huge amounts of memory, even when not needed... And if we need it (for file upload of files > 1 MB or so), even that is not enough. Seems like file-upload is the only case that needs more memory for input-buffering (since we don't want to write tmp-files). Accent marks in titles. spÈkjes. REAL name: 1 single real name, as stored in the revision-document. URL name(s): To use in URLs, there may be more, leading to the same document on the server. FILE name: 1 single canonical (simplified) name for the local filesystem. I want accent marks to be allowed in the REALNAME only. Maybe, the should be allowed in the URL as well, but the preferred way would be %XX notation (escaping with percent-mark, encoding in hex)? An initial documentname comes from a reference, or is typed in manually in the location bar of the browser... FIX..... 10: THANKS ========== Thanks to Sam Roig and Martin Laeuter for reporting compilation problems under Linux, OSX and FreeBSD on Mac. Thanks to Simon Asselbergs and to Anton Woldhek for interface-suggestions, ideas and bug-reports.