What is Shardia?
Features of Shardia
How to Install
Rights for files
File Descriptions

What is Shardia?
Shardia is a program that is designed to replace Apache's standard fancy filelisting. Shardia generates a dynamic filelisting for every directory that you tell it to share, and allows users to browse and download the files in those directories.

Features of Shardia

If you have never installed this program before, you will need to download the shardiaX-themes.zip file, where X is the version number. If you are upgrading, you will want the shardiaX-nothemes.zip file.

shardiaX-themes.zip has the program code and the datafiles for the program to run. Right now, the datafiles consist entirely of the themes information. The themes.db file tells Shardia which file extensions are what type, and what icon to use, as well as which themes are installed.
shardiaX-nothemes.zip only has the program code. This file is intended to be an upgrade installation. It should overwrite the old installation, but it would be wise to just look at the new shardia.conf file, instead of overwriting your current settings, and use the new settings contained in the new file. Every released version of shardia.conf contains all of the settings supported by the program.
The newer versions can work without a themes file, but they won't work especially well. For example, Shardia will not know which files are what types, as that information is in the themes.db file. None of the file icons will show up, because the pictures are stored in the themes directory.

Now that you have downloaded the correct file, you will need to extract it and place the files into their appropriate destination. shardia.py, shardiadl.py, shardiatheme.py, and shardia.conf all need to go into your web server's cgi-bin directory. You might need to check the location of your installation of Python and make sure the first line of all 3 script files points to it. Apache's user will need to read all 4 files, and it will need to edit shardia.conf if you want Shardia's admin to be able to change the settings through the web interface.
You also need to place the Shardia datafiles into a place that can be read by apache. For example, /var/www/shardia is a possible location. You need to edit the shardia.conf file to point to where you placed this directory. Rule of thumb: If the location of the themes.db file is /var/www/shardia/themes.db, your shardia.conf file's workdir should point to /var/www/shardia/

Rights Due to Linux's fine security model, the rights of these files need to be special. The Shardia data files, placed, in our example in /var/www/shardia/, should be able to be explored and read by Apache. For example, each theme directory could have mode 755 and every file 644. However, the /var/www/shardia/ data directory must also be writable by Apache. This is because Shardia will create the temporary zip files to be downloaded here, and the file descriptions are stored here. This directory could have a mode of 777.
The scripts also need to be executable by Apache. shardia.py, shardiadl.py, and shardiatheme.py should be mode 755 in order for Apache to be able to run them. shardiathemeconf.py does not need executable priveleges, as it is a shell program and not a CGI program. The settings file, shardia.conf, needs write access by Apache, for example, 666.
A lot of trouble could be saved by making Apache own all of these files, but that is up to you to decide.

Inside the shardia.conf file, there are various name=param settings. Some of them, like customhead and custombody, can have multiple lines. Here follows a description of all the settings that are possible in this file.
Setting name Description
localdir This is the root of the directory that you want to share with Shardia. For example, /mnt/archives/. You should place a / after this setting, but I don't think it is entirely necessary.
workdir This is the location of Shardia's datafiles. This is also the location of Shardia's temporary files. For example, while creating the zip file of a directory to be downloaded, it is stored in this directory. If the themes.db file is located in /var/www/shardia, then this setting would be /var/www/shardia/. This setting must have a / at the end.
hidden This is a multiline setting. Each directory that you want to hide is listed on its own line. Each directory is relative to localdir. For example, if you are sharing /mnt/archives and you want to hide /mnt/archives/priv, one of the lines in this setting would be /priv. Every entry in this setting must begin with a /.
servername This is the name of your particular server. It is placed in the titlebar of the browser's window. If you don't want to think up a creative name, you should put in Shardia.
defaulttheme This is a number that specifies which theme should be the default for users that haven't chosen a theme. It is preferably set by the admin's configuration screen, as in that screen you can see which theme's name is selected.
maxzipsize This is the size in bytes that the list of files to be placed into a directory's zip file should not exceed.
customhead This is a multiline setting. This is a block of text that will be added to the field of every page in the program. This can be used to edit the CSS styles. The default shardia.conf file contains a complete stylesheet in this field, that defines a style for every element in the program, as well as containing comments describing which elements are where in the program.
custombody This is a multiline settings. This is a block of text that will be added after . You should place a tag in this section. By default, Shardia will not add one.
nfobox This setting contains the dimensions of the NFO Header box, in characters. For example: nfobox=81,30
userlist This is a list of users that can log in. The first user is the admin, and has more rights in the program.
passlist This is a list of passwords for the users. Each password matches exactly to the respective user in userlist. Examine the default shardia.conf file for an example of this. The first user in userlist has the first password in passlist.
adminlist This is a comma separated list of users who are also considered to be admins. They have all the rights of the normal admin (the first user in userlist), except that they can't edit this list through the configuration screen. There should be no spaces in this area. For example: "adminlist=user,user2,user3,someone,someoneelse,somebody"

The Shardia themeing system is very simple. Every extension is associated with a filetype in themes.db. Every filetype has an image file and a description. This description is shown in Shardia's filelistings under File Type. Every filetype can have a parent filetype. This parent filetype's icon is used if the preferred filetype's icon doesn't exist in a certain theme.
For example, a bitmap file, entitled test.bmp, has the extension bmp and is therefore associate with the bitmap filetype. It is shown as a Bitmap Picture under File Type. However, if a theme doesn't have a bitmap.png file, the bitmap's parent filetype, image, is used instead. If, however, image.png doesn't exist in the current theme, it looks to see if image has a parent filetype. It doesn't, so it tries to use the special unknown filetype's icon. If unknown.png doesn't exist, it will not show an icon.

The themes.db file contains the list of filetypes to icon mapping. If you intend to create your own themes, you will need to extract shardiathemeconf.py to your cgi-bin directory. It needs to be in this location because it looks in the same directory for shardia.conf, which it uses to locate the themes.db file. It does not need to be run by Apache, so you can make the rights more restrictive for it. If you intend to make your own theme, you might want to use shardiathemeconf.py to display a treeview of the filetypes mapping. This view can help you decide which icons have to be named what. You will also have to Edit Registered Themes, and tell it to add a new theme. It won't create the directory for you, you will have to do that yourself.
Every filename should be lowercase. You will need to at least have an unknown.png file. More icons that are probably necessary are the folder.png, folder_up.png, and folder_zip.png icons.
Enjoy creating your own themes! If you finish one, you could email the updated themes.db and your theme directory to snes_rocks AT users DOT sourceforge DOT net and I will add it to the next release!

File Descriptions
In Shardia's data directory, there might be a file called files.db. This file contains the descriptions of all the files that you created a description for. If you want to clear all the descriptions, just delete this file. It will be created automatically when you create a file description.

Another feature that is contained in this program is the ability to show a directory header before every file listing. To do this, you need to create a .nfo file in the directory you want to create a header for. The program will print out all found *.nfo files.

Any files that begin with . will not be shown, unless the admin is logged in.

Project Webpage
Download Shardia
Example Setup

Hosted by:
SourceForge.net Logo