__ ___ __ ____ _ _ _ _ ____ _ __ | | / / / _/ / __ \ | |/_| | | / / / ___\ | / _| | |/ / \ \__ ( ____) | / | |/ / ( ____) | / | ( \_ \ \____/ |_| |___/ \____/ |_| | |\ \ __/ / _ __ _ __ ____ ####### |__| \__\ /___/ | | / \ | | / / / __ \ ## ## _ | | / /\ \ | '/ / / / \ \ ## ## 2.0.1 | |_| | / ___ \ | . \ \ \__/ / ## ## \____| /_/ \__\ |_|\__\ \____/ ####### © 2008-2010, Riku Eskelinen/ KServer Software Development ________________________________________________________________________________ README Thank you for selecting KServer Jako 2.0 as your file sharing platform software. This README guides you through easy installation steps and helps you to tweak KServer Jako to suit your needs. First, check that your server is compatible with following requirements: - PHP 5.2 or newer - At least 1MB of free space - PHP support for FInfo and working MIME magic file (not required, but large portion of KSJ functionality depends on this) - PHP support for EXIF data (not required, but you have to blacklist 'exif') - PHP support for ID3 tags (not required, but you have to blacklist 'id3') - PHP support for unzipping archives (not required, but you have to blacklist 'unzip') - Jako's main folder has to be writable by web server, and there cannot be any conflicting files - finfo.cache should be creatable, readable and writable (not required, but you have to disable finfo cache, which creates major performance degradation). Then unzip jako folder and upload it to your server. Check that files are unharmed and everything looks OK. Then check that Jako's main folder is set to listable, readable and writable by your web server. On *nix/ *pache, that would be "chown -R www-data:www-data jakodirhere/ && chmod 700 -R jakodirhere/". You might want to experiment with that to suit your needs. Then open up config.php. I'll walk you through with that one: For Jako's and your own sake, do not remove any config values, that might break the whole thing. Also check that you close all quotes and parenthesis. As Jako might have changed since this documentation was written, some options might not be available, might be in different order, or there might be options not documented here. See config.php's comments if unsure. * Default language - $config['lang'] Set your default language here. Jako will fall back to it if unsure of user's preference. You need to actually have this language installed in lang/ folder. * Style file - $config['style'] Set your style file here. By default this is Jako's default theme, cleverly named 'default'. If you have your own css file, put it into styles/ folder and set its name, without .css, here and Jako should load it instead. * Site name - $config['sitename'] Your site's name. Only use plain text. * Site logo - $config['logo'] Your logo. It will be shown besides your site name and links (see below). If you prefer not to have one, set this to false. * Links - $config['links'] Links you want to show. You can have it without links, just set it as array();. If you wish to have more links, just follow the examples. * Site description - $config['description'] You can have your long description here. If you want, you can use HTML to customize it. If you would like to keep that space unoccupied, set this to false. * Hidden files - $config['hiddenfiles'] These files are not shown on list, and cannot be uploaded. It is enough to put only part of file name here, Jako will check if file includes any of these phrases and will hide it from the list or abort upload, if it has those. You should keep the default values, unless you know better. Those are for your own protection. * Protected files - $config['protectedfiles'] These files are also hidden from the list, but naming must be exact. Users are unable to upload files named exactly as these. * Hide dotted files - $config['hidedotted'] In UNIX, hidden files are usually named starting with dot ("."). Jako can show these files, if you want. Set this to true to see them also. If you don't know any good reason to do so, let this be true. Note, that uploading hidden files is still not allowed, as that is Jako's internal protection mechanism and cannot be altered by config. * MIME magic file - $config['mimemagic'] In order to Jako to detect file types, it asks File Info ("Finfo") utility to provide such info. Finfo needs to use your system's database of known file types, also known as MIME types. Note that Jako does not care about file extension/ suffix, and relies entirely to that MIME magic file via Finfo utility. Set here the path to your MIME magic database file, or set it to null or "" to let Finfo guess the location. If that fails, however, you will see all files as application/octet-stream files and no actions are provided. * Authorization method - $config['auth'] You can log in to the system as an administrator in many ways, and the way of logging in is specified here. If this is set to 'simple', simple login is used. It does not need data- base in order to work, and relies to config values, cookies and login.php creation. If this is set to 'none', login is disabled altogether. * Simple authorization password - $config['password'] If you chose to use simple authorization, set your password as plain text here. I recommend choosing strong password, as the system is not protected against dictionary attacks. If you use other than simple auth, this option value does not affect anything. * Illegal files to upload - $config['illegalfiles'] If file includes strings set here, it cannot be uploaded. If file is moved to the directory via other mechanisms (f. ex. via FTP or SSH), it will, however, be shown. Again, if you're unsure, do not remove the default entries. * Blacklisted plug-ins - $config['blacklist'] You can list plug-ins you don't want to use here by listing them inside array(...), f. ex. array('id3','exif'). The list of default plug-ins is included in this document. * Show disk space status - $config['showspace'] If you don't want users to see, how much disk space Jako has, you can set this to false. If true, the disk total space, free space and percentage of that will be shown in the footer. If false, then they won't. Disk space limitations are in effect regardless of this setting. * Limit the time Jako can run - $config['maxruntime'] If Jako hogs too much computing power for some reason, you can set this value. If set, Jako will detect when it has used too much time and then stop listing files. It will, however, cleanly stop, and therefore will require a little more time than specified here. Give time in seconds (0.5, for example, is good too) or set to false to let Jako run all the time it needs to (if PHP won't stop it). * Allow language changing - $config['langs'] If you want to let your users to change language, you can specify those languages here. If you have more than 1 language, the language choosing form will be shown. Be sure to actually having those language files. * Use File info cache - $config['finfocache'] As mentioned earlier, Jako uses Finfo utility to determine the file type. Finfo queries, however, are quite slow and processor intensive. Therefore Jako can use its cache of known files and their MIME types, which will dramatically speed up file listing. This has a few drawbacks: if file's type is somehow changed, its MIME type will be shown wrongly. Also, if something goes wrong in cache algorithm, it is possible that finfo.cache file starts to bloat. You should remove finfo.cache from time to time, and let Jako build it again. Cache is automatically incremented by the details of a file not already in cache. If you think that Finfo cache is not good for you, you can set this to false and Jako will query each file's MIME type every time it is listed. * Free disk space limit - $config['mindisk'] If you have limited disk space, or you use other sites alongside Jako, you might want to set this to limit to preserve at least some disk space for everything else. This configuration value takes its input in bytes, but using X*pow(1024,2) for megabytes or X*pow(1024,3) for gigabytes is good too. If Jako's directory has less space than defined here, upload option will be disabled. Also, if there is initially enough space but uploaded file would cause the disk space to decrease below this level, Jako will not allow uploading such a file. You can set this to false or 0 to allow uploading anyways. To disable uploading altogether, set this to disk_total_space('./'). * Temporary file storage for plug-ins - $config['tempdir'] Some 3rd party plug-ins might require to use temporary file storage, which is set here. In UNIX that would probably be something like '/tmp', and in Windows something like 'C:\Temp\'. Official Jako plugins and internals will use PHP default tempdir. * Uploading logging mechanism - $config['logging'] When files are uploaded, it might be useful to log uploading info for use in abuse situations or similar. Jako provides currently two methods: Set this to "none" and no logging will be done, or set this to "simple" and Jako will write uploading time, file name and sending ip to upload.log. * Uploading multiple files at once - $config['maxfiles'] In Jako 2.0.1, it is now possible to upload multiple files by once using HTML5's new multiple attribute and Jako's so-called MultiAdd feature. This should be set to min(X,ini_get('max_file_uploads')), where X re- presents the amount of files user should really be uploading. There is no point setting it over max_file_uploads, as PHP will not allow that. To disable MultiAdd altogether, set this to 1 or less. Setting this to 0 or lower will not disable uploading, see mindisk for that. After configuring, save, and you're good to go. PLUGINS Jako uses so-called plugins or modules to give user previews in many different formats. You might not like your users to see all this data, so you have the freedom to disable some of them by setting them into blacklist (described above). By default, all plugins are enabled. Here is explanation for official Jako plugins as of Jako version 2.0.1: Name | Description | Supported types ----------------+---------------------------------------+----------------------- audio | Provides ability to listen tracks via | audio/mpeg | onscreen player. By default HTML5 | audio/x-wav | audio is tried and browsers not | application/ogg | supporting it can fall back to | | embedding audio, which will cause | | browser to launch it's plugins to play| | audio. User can also force embed-mode,| | if their browser does not work with | | HTML5 player. | | | dirlist | Provides support for seeing directory | directory | contents beforehand. Has safety | | mechanisms in place to disable it when| | file listing might be not wanted, i.e.| | when at least one of .htaccess, | | index.htm, index.html or index.php | | exists. | | | exif | Provides image's EXIF data. | image/jpeg | | flash | Provides embedding ability for SWF | application/x-shockwav | files, making it possible to play them| e-flash | while reading file listing. | | | flowplayer | Provides ability to play FLV videos on| video/x-flv | FlowPlayer Flash player by Flowplayer | | Oy, which is provided by default. | | | id3 | If your server supports reading ID3 | audio/mpeg | tags (PHP plugin id3), users can view | | MP3 file's metadata via this plugin. | | | iframe | Provides previewing of XML and HTML | text/html | content via HTML's iframe. | application/xml | | image | Provides simple image previewing, does| image/png | not actually create thumbnails, but | image/jpeg | asks browser to show full-size image | image/gif | shrinked. | | | odfinfo | Provides ODF metadata display, | application/vnd.oasis. | including creator, editor, statistics | opendocument.text | and more. ZIP support required. | | | svg | Provides SVG display via embedding | image/svg+xml | support. | | | unzip | Provides list of zip file contents, | application/zip | server must support reading zip files.| | | video | Provides ability similar to "audio" | video/x-msvideo | plugin to play video files via on- | video/x-flv | screen player. It uses HTML5 video and| | falls back to embed. It is also | | possible to user to force embedding. | | | xmlsrc | Provides snippet of file's source | text/html | code for previewing. | application/xml | | text/plain | | text/x-pascal QUESTIONS AND ANSWERS ===================== I planned to make a FAQ, but as nobody ever asks anything, it would be awkward to call it _frequently_ asked questions. So, here is some questions I think you might want to ask, and answers to them. Q: May I use this in my site? A: Definitely yes. Q: May I use this in my site, even if it has commercial purpose? A: Yes, even then. Finnish laws require me to not ask for donations, but if you would like to buy voluntary license for your commercial use, you're free to contact me. Q: May I use my own/ somebody else's language and/or style file? A: Yes, and you're recommended to tailor the stylesheet to better suit your needs. See the following Q&A for details. Q: May I redistribute said language and/or style files? A: It depends. If you got them from somebody else, you should ask for permission to do so. If you created your own ones, you're free to do so with any license you might want, even commercially. You are not, however, allowed to bundle them with Jako and distribute such a package. Q: May I customize/ enhance Jako? A: Yes, and if you do not redistribute it, you can do it without publishing source code. If you wish to distribute it, see next Q&A. Q: I changed Jako and I want to publish it. What to do? A: You are encouraged to make Jako better. If you decide to make your own version, so-called fork, you are required to publish it under GNU GPL 3 or later. You are not allowed to use our trademarks in confusing matter: you need to change software name to something else than 'KServerJako'. You are encouraged to change the footer to some- thing like "MyCoolSoftware © 2010, Me; based on KServerJako © 2008- 2010, Riku Eskelinen/ KServer Software Development". See gnu-gpl3.txt and AUTHORS for details. Q: What if I cannot publish source code? Am I not allowed to distribute it? A: You cannot distribute software based on Jako if you are not able to provide source code if required by somebody who got your software. If you really need to make your software under other licenses, you're first required to remove Flowplayer functionality from your code, as that is licenced under GNU GPL3 from Flowplayer Oy. You must also retain attribution of Silk Icons as required by CC-BY-3.0, or replace it by your own icon theme. Lastly, you need to contact me for details. Be prepared to pay huge amounts of money as licensing costs. Q: I know how you could make Jako better or I have new language file/ theme file. How can I help? A: Suggestions are welcome, see contact details below. If you want to give your translation or theme file to be used in Jako, you are free to do so. Be aware, however, that your commitments can be dropped in any commercial version of Jako or derivates. You are allowed, and encouraged, to publish your work under Public Domain or similar license, to keep your work in commercial versions too. Q: Why bother creating such list of questions? A: I really don't know. Personally, I think nobody would bother to read these anyway, but if you actually did, let me know. Q: I found a bug. What should I do? A: File a bug on http://bugs.kserver.dy.fi under Jako 2.0, and I'll see what I can do about it. If you wish not to file bug, you can also contact me and tell me about it. Q: Are there any third party software used in Jako? A: Yes. Jako uses Silk Icons by Mark James, licensed under CC-BY-3.0. Jako also uses Flowplayer by Flowplayer Oy, licensed under GNU GPL 3. You can see more detailed author information in AUTHORS file. Q: What does "Riku Eskelinen/ KServer Software Development" mean? A: It is precaution for future use, mostly. Currently all Jako's own code is 100% written by me, but if that changes, the "KServer Software Development" would be the catch-all copyright holder. That is also a precaution for my unforeseeable cessation of life, in which case the copyright of Jako won't be stuck with my estate, and work around Jako can continue. Q: How can I contact you? A: You should usually contact me via e-mail . If you would, however, send me ordinary mail, send it to: KServer Software Development KServer Jako/ Riku Eskelinen Lotilantie 1 A4 40530 JYVÄSKYLÄ FINLAND Also, see Jako's web page (in Finnish) at: