 |
VTFileman
|
Documentation
The software is offered under GNU LGPL. It has been tailored for the Virginia Tech community. Therefore you may have to do a number of changes to adapt it to your needs. Because of our limited resources we cannot give any support for the installation of required middleware or the VTFileman software itself. However, you could try the discussion forum or if you find bugs or have recommendations for improvements please use our bug reporting tool or feature tracker.
Caution!
Since VTFileman requires the integration with an LDAP server to handle authentication and with a web server (e.g., Apache) to handle document download, its installation is not trivial and requires some knowledge of Java, application servers (e.g., Tomcat), web servers (e.g., Apache) and LDAP. Please do not attempt to install VTFileman if you don't feel comfortable with these technologies as it is likely not to work and perhaps cause security vulnerabilities.
Architecture
VTFileman is a java web application and needs a java web server such as Tomcat in order to run. Also, VTFileman is typically used in conjunction with a web server (e.g. Apache) that can deliver the documents stored in the users' home directories. You can either just have one web server serving documents in cleartext via HTTP or you can have a second web server that enables document transfer via an encrypted connection, i.e. HTTPS.
Furthermore, you can give your users an alternative way to upload and manage files by providing a WebDAV server. This may be useful if your users regularly have to upload many files at once (VTFileman only supports the upload of a few files at a time).
The permission feature in VTFileman will generate access control files in the Apache .htaccess syntax for all three servers. By default those files are called ".htaccess", ".htaccess.ssl", ".davaccess".
An LDAP server is used for authenticating users' logins. The figure below shows the system architecture for using VTFileman.
Installation Instructions for VTFileman
VTFileman is a pretty flexible and customizable application. However, we strongly recommend that you closely follow the installation instructions using the defaults shown below. After the application is up and running you can adapt the installation to your needs.
Step 1: Install Java application server
VTFileman is a 100%-Java compliant application and should work with any Java application server that supports JDK 1.4 (JDK 1.3 does not suffice since it does not support regular expressions which are heavily used in VTFileman). If you don't have one yet, we recommend to install the free Apache Tomcat server. The Tomcat server is a Java application itself. Therefore you may have to install Sun's JDK 1.4 before you can run Tomcat.
In the following we assume that you don't have anything installed yet. Otherwise just jump steps as appropriate.
Microsoft Windows
- Download and install Sun's Java 2 Standard Edition, SDK 1.4 (J2SE SDK), Version: "Windows (all languages, including English)" (install in folder e.g. "C:\j2sdk1.4.2_08", use defaults)
- set the JAVA_HOME environment variable to the folder that you installed Java in, e.g. "set JAVA_HOME=c:\j2sdk1.4.2_08"; You should make this a permanent setting by adding JAVA_HOME as an environment variable; e.g.: in Windows XP through Control Panel/(Performance and Maintenance/)System/Advanced/
Environment Variables/
System Variables/New" (do not have a trailing backslash or semicolon at the end)
- Download and install Tomcat (e.g. jakarta-tomcat-4.1.31.exe); if the previous link does not work check out the offical Tomcat website: (install Tomcat into a folder called "\usr\local\tomcat\")
|
Unix (Linux, Solaris, etc.)
- Download and install Sun's Java 2 Standard Edition, SDK 1.4 (J2SE SDK) for your platform (use defaults)
- set the JAVA_HOME variable to the folder that your Java installation is located in
- Download and install Tomcat (e.g. jakarta-tomcat-4.1.31.tar.gz); if the previous link does not work check out the offical Tomcat website: (install Tomcat into a directory called "/usr/local/tomcat/")
|
Step 2: Download and unpack VTFileman
Step 3: Setup file system
- prepare a directory that will contain the user directories, e.g. /usr/local/apache/htdocs/
- copy the admin folder contained in the zip file (and all its contents) into this directory
- copy the fileman_data folder contained in the zip file (and all its contents) into this directory
- You should now have the following directory structure:
/usr/local/apache/htdocs/admin/.home.xml
/usr/local/apache/htdocs/admin/about.html
/usr/local/apache/htdocs/admin/announce.html
/usr/local/apache/htdocs/admin/footer.html
/usr/local/apache/htdocs/admin/header.html
/usr/local/apache/htdocs/admin/news.html
/usr/local/apache/htdocs/fileman_data/groups.dtd
/usr/local/apache/htdocs/fileman_data/home.dtd
/usr/local/apache/htdocs/fileman_data/localUsers.dtd
/usr/local/apache/htdocs/fileman_data/perms.dtd
- If you use a directory other than /usr/local/apache/htdocs/ you will have to modify the file /usr/local/apache/htdocs/admin/.home.xml to make sure the reference to the file home.dtd is correct
Step 4: Start & Test
- Copy vtfileman.war into the Tomcat webapps folder (typically /usr/local/tomcat/webapps/)
- Start tomcat (e.g. /usr/local/tomcat/bin/startup.sh)Tomcat should now create a directory called vtfileman within its webapps folder
- VTFileman should be up and running by now. By default, Tomcat listens on port 8080. Therefore you will probably have to enter something like http://localhost:8080/vtfileman/ in your web-browser in order to verify that the application is running. If everything is correctly installed you should be able to login as admin (default password is: adminpass). Using the admin password you can login to ANY user-account. This is handy for the helpdesk staff but also dangerous. Therefore, your admin password should be very strong. More about that later.
- If you logged in successfully you can proceed to tailor VTFileman to your needs.
Step 5: Tailor VTFileman to your needs
- Change the admin password! Call http://localhost:8080/vtfileman/encryptPassword.jsp and choose a password; then copy&paste the encrypted password into the adminPasswordCrypt parameter in the file /usr/local/tomcat/webapps/vtfileman/WEB-INF/web.xml
- The file /usr/local/tomcat/webapps/vtfileman/WEB-INF/web.xml contains all the customization information for VTFileman along with some documentation
- Apapt at least the following parameters to your needs:
- hostName
- rootURL
- filesysRoot
- dtdPath
- logRoot
- adminEmail
- cryptSalt
- adminPasswordCrypt
- ldap... (all parameters that configure the connection with the LDAP authentication and name lookup server)
- Shutdown and restart Tomcat. Your changes should have taken effect
- Go to http://localhost:8080/vtfileman/ and try to login to VTFileman as "admin" using the newly chosen password and then logout
- Try to login as any other user contained in your LDAP server. If the authentication fails, double-check the LDAP parameters in the web.xml file
- If you run into problem with the LDAP integration, you may want to enable debug messages by modifying the file /usr/local/tomcat/webapps/vtfileman/WEB-INF/classes/log4j.properties
Installation Instructions for Apache (Document file servers non-SSL and SSL, WebDAV server)
Note that these servers are optional and not required to run VTFileman.
Step 1: Setup Apache as a document file server (non-SSL)
- Download Apache web server and install it into /usr/local/apache/ using the default configuration
- Apart from the standard parameters, the Apache configuration file (e.g., /usr/local/apache/conf/httpd.conf) should contain the following settings:
DocumentRoot /usr/local/apache/htdocs/
AccessFileName .htaccess
# by default, forbid all access
<Directory "/usr/local/apache/htdocs/">
Options Indexes FollowSymLinks
Options +IncludesNOEXEC
AllowOverride All
Order allow,deny
Deny from all
</Directory>
# disallow the viewing of hidden files (which contain permissions etc.)
<Files ~ "^\.">
Order allow,deny
Deny from all
</Files>
- Start an Apache instance using the configuration file /usr/local/apache/conf/httpd.conf
Step 2: Setup Apache as a document file server (SSL)
- create a copy of the Apache configuration and name it httpd.conf.SSL
- Apart from the standard parameters, the Apache configuration file should contain the following settings:
DocumentRoot /usr/local/apache/htdocs/
AccessFileName .htaccess.ssl
# by default, forbid all access
<Directory "/usr/local/apache/htdocs/">
Options Indexes FollowSymLinks
Options +IncludesNOEXEC
AllowOverride All
Order allow,deny
Deny from all
</Directory>
# disallow the viewing of hidden files (which contain permissions etc.)
<Files ~ "^\.">
Order allow,deny
Deny from all
</Files>
- Start an Apache instance using the configuration file /usr/local/apache/conf/httpd.conf.SSL
Step 3: Setup Apache as a WebDAV file server
- create a copy of the Apache configuration and name it httpd.conf.DAV
- Apart from the standard parameters, the Apache configuration file should contain the following settings:
DocumentRoot /usr/local/apache/htdocs/
AccessFileName .davaccess
# by default, forbid all access
<Directory "/usr/local/apache/htdocs/">
Options Indexes FollowSymLinks
AllowOverride All
Order allow,deny
Deny from all
DAV On
AuthType Basic
AuthLDAPAuthoritative off
AuthName "Please login"
AuthLDAPURL ldap://ldap.yourorg.com/ou=something,dc=something,dc=something?uid
AuthLDAPStartTLS on
</Directory>
# disallow the viewing of hidden files (which contain permissions etc.)
<Files ~ "^\.">
Order allow,deny
Deny from all
</Files>
# allow "._" resource fork files are created by MacOS X
<Files ~ "^\._">
Order allow,deny
Allow from all
</Files>
<Files ~ "^\.DS_Store">
Order allow,deny
Allow from all
</Files>
- Start an Apache instance using the configuration file /usr/local/apache/conf/httpd.conf.DAV
If you have questions or comments please use the discussion forum.
http://vtfileman.sourceforge.net/
Last modified:
June 6, 2005
|
web hosting kindly provided by  |