This document was uploaded by user and they confirmed that they have the permission to share
it. If you are author or own the copyright of this book, please report to us by using this DMCA
report form. Report DMCA
Contents 1 HOW TO READ THIS MANUAL ...............................................................................................................................1 2 INSTALLATION OF THE BSCW SERVER .............................................................................................................2 2.1 GENERAL REQUIREMENTS ...............................................................................................................................................2 2.2 UPGRADING TO BSCW 4.2 ..........................................................................................................................................2 3 INSTALLATION PROCEDURE FOR UNIX ............................................................................................................6 3.1 SYSTEM REQUIREMENTS ..................................................................................................................................................6 3.2 INSTALLATION ..............................................................................................................................................................6 3.3 CONFIGURATION ............................................................................................................................................................8 3.3.1 HTTP server configuration ..............................................................................................................................8 3.3.2 BSCW instance configuration ...........................................................................................................................9 3.3.3 Administrator account registration ................................................................................................................10 3.4 DATABASE SERVER, GARBAGE COLLECTION AND BACKUP ................................................................................................11 3.5 BSCW SERVICES .......................................................................................................................................................13 3.5.1 Indexing / Document Contents Search ...........................................................................................................13 3.5.2 Folder Mail Delivery ......................................................................................................................................15 4 INSTALLATION PROCEDURE FOR WINDOWS 2003/XP/2000/NT .................................................................21 4.1 SYSTEM REQUIREMENTS ................................................................................................................................................21 4.2 INSTALLATION AND CONFIGURATION ...............................................................................................................................21 4.3 DATABASE SERVER AND GARBAGE COLLECTION ..............................................................................................................24 4.4 TASK SCHEDULER ......................................................................................................................................................25 4.5 FURTHER CONFIGURATION DETAILS ...............................................................................................................................26 4.5.1 BSCW Server Root Definition .......................................................................................................................26 4.5.2 IIS Configuration ...........................................................................................................................................26 4.5.3 Apache HTTP Server Configuration .............................................................................................................27 4.5.4 BSCW Registry Settings ..................................................................................................................................28 4.5.5 De-Installation ...............................................................................................................................................29 4.6 BSCW SERVICES .......................................................................................................................................................29 4.6.1 Configuration of the Microsoft Index Server ..................................................................................................29 4.6.2 Folder Mail Delivery ......................................................................................................................................29 5 CONFIGURATION OF BSCW SERVERS ..............................................................................................................30 5.1 CONFIG.PY .................................................................................................................................................................30 5.1.1 Section 1: MANDATORY server settings .......................................................................................................31 5.1.2 Section 2: Mail handling ................................................................................................................................32 5.1.3 Section 3: Server access .................................................................................................................................33 5.1.4 Section 4: web/proxy server settings ..............................................................................................................36 5.1.5 Section 5: BSCW appearance settings ...........................................................................................................40 5.1.6 Section 6: Optional BSCW services ...............................................................................................................43 5.1.7 Section 7: BSCW database server settings .....................................................................................................48 5.2 CONFIG_HTML_UI.PY ....................................................................................................................................................50 5.3 LG_MSGCONFIG.PY .......................................................................................................................................................51 5.4 CONFIG_ICON.PY ..........................................................................................................................................................52 5.5 CONFIG_MSG.PY ...........................................................................................................................................................53 5.6 CONFIG_MIME.PY ........................................................................................................................................................53 5.7 CONFIG_CONVERT.PY ...................................................................................................................................................53 5.8 CONFIG_MEET.PY .........................................................................................................................................................56 5.9 CONFIG_CAL.PY ..........................................................................................................................................................57 6 ADMINISTRATION OF BSCW SERVERS ............................................................................................................58 6.1 ADMINISTRATION THROUGH THE HTML INTERFACES ......................................................................................................58 6.2 ADMINISTRATION THROUGH THE BSADMIN SCRIPT .............................................................................................................62 6.3 USER ADMINISTRATION ................................................................................................................................................64
i
BSCW 4.2 Administration Manual 6.3.1 Additional anonymous users ...........................................................................................................................65 6.3.2 User registration with bsadmin register .........................................................................................................66 6.4 X-BSCW API .........................................................................................................................................................66 6.5 USER NOTIFICATION SERVICES (UNO) ..........................................................................................................................67 6.6 WEBDAV ................................................................................................................................................................69 6.6.1 Installation ......................................................................................................................................................69 6.6.2 Microsoft Support for WebDAV ....................................................................................................................70 6.7 LDAP ......................................................................................................................................................................71 6.7.1 Installation ......................................................................................................................................................71 6.7.2 LDAP Browser ................................................................................................................................................73 6.8 WEB SEARCH WITH GOOGLE WEB APIS SERVICE ...........................................................................................................73 6.9 QUOTA - DISK USAGE LIMITATION ................................................................................................................................74 6.9.1 Limit Classes ...................................................................................................................................................76 6.9.2 Quota Activation .............................................................................................................................................77 6.9.3 Calculation of current disk usage ...................................................................................................................78 6.9.4 Report disk usage ............................................................................................................................................78 6.10 DEFINITION OF ROLES ................................................................................................................................................78 6.10.1 The BSCW role concept ................................................................................................................................79 6.10.2 Role definition and default roles ..................................................................................................................81 6.10.3 Site-specific Roles .........................................................................................................................................83 6.11 SITE-SPECIFIC BANNER ................................................................................................................................................85 6.12 SOME USEFUL HINTS ...................................................................................................................................................85 7 BSCW HELP .................................................................................................................................................................87 7.1 LANGUAGES ...............................................................................................................................................................87 7.1.1 Existing translations .......................................................................................................................................87 7.1.2 Translation instructions .................................................................................................................................87 7.2 BSCW UPDATES .......................................................................................................................................................89 7.2.1 New Versions ..................................................................................................................................................89 7.2.2 WWW Search Engines ....................................................................................................................................89 8 BSCW LICENSE .........................................................................................................................................................90 9 FREQUENTLY ASKED QUESTIONS (FAQ) ........................................................................................................91 9.1 BSCW SERVER USAGE ..............................................................................................................................................91 9.1.1 What do I need to use BSCW? ........................................................................................................................91 9.1.2 Do I need a helper application for uploading documents? Why? ..................................................................91 9.1.3 Why do I get a 'save as' dialog box when I click on 'add document'? ............................................................91 9.1.4 I've forgotten my user name/password - what do I do? ..................................................................................92 9.1.5 Why don't objects I add to a workspace appear in the workspace listing? ....................................................92 9.1.6 Why are my Macintosh documents 'unreadable' when I download them? .....................................................92 9.1.7 When I download a Word document, why do I get an error message? ..........................................................92 9.1.8 How can I change my password? ...................................................................................................................92 9.1.9 How can I remove (destroy) a workspace? ....................................................................................................93 9.1.10 Why do I get a Javascript error in some workspaces? .................................................................................93 9.1.11 BSCW does not accept my password - what can I do? .................................................................................93 9.1.12 I've reached the limit of my disk space .........................................................................................................93 9.1.13 Why do I get binary junk when I print (or 'view source') any of the workspace content pages? .................94 9.1.14 Why is in the export operation the FTP password not stored? ....................................................................94 9.1.15 Why does MS-Word mark a document as 'read-Only' when it is downloaded from a BSCW server? .........95 9.2 BSCW SERVER SOFTWARE .........................................................................................................................................95 9.2.1 What do I have to do to get BSCW software? ................................................................................................95 9.2.2 How do I keep up to date with developments and new releases? ...................................................................95 9.2.3 Can I try the BSCW software online? .............................................................................................................95 9.3 BSCW SERVER ADMINISTRATION ................................................................................................................................95 9.3.1 What facilities are available for server administrators? ...............................................................................95 9.3.2 How can I delete a user from our server? ......................................................................................................96 9.3.3 How can I rename a user? ..............................................................................................................................96 9.3.4 How can I register a user quickly (i.e. without sending email)? ....................................................................96 9.3.5 How can I restrict creation of new workspaces? ...........................................................................................96 9.3.6 How do I find the disk file for a document in a workspace? ..........................................................................96
ii
BSCW 4.2 Administration Manual 9.3.7 There are some files in the BSCW Temp directory - can I remove them? .....................................................97 9.3.8 How do I upgrade my current BSCW server instance to a new version? ......................................................97 9.3.9 How do I copy my BSCW database to another host. ......................................................................................98 9.3.10 Why do email invitation messages never arrive? .........................................................................................98 9.3.11 Why do I get a "licence expired" error? .......................................................................................................98 9.3.12 The BSCW server does not work any more, the BSCW database seems to be corrupt. How can I fix it? ...99 9.3.13 Why does the Web search not create any results anymore? ......................................................................101 9.3.14 Why do I get connect problems during "Upgrade License"? .....................................................................101 9.3.15 My BSCW database (version 3.4 and later) seems to be corrupt, what can I do? .....................................101 9.3.16 Why do I get an error, when I want to convert or archive files at a server running Internet Information Services (IIS) 6.0 on Windows 2003? ....................................................................................................102 9.3.17 Why is it impossible to connect via WebDAV to a BSCW server running on a Windows System using the Internet Information Services (IIS)? ......................................................................................................102 9.4 BSCW INSTALLATION ..............................................................................................................................................103 9.4.1 What do I need to install the BSCW server software? ..................................................................................103 9.4.2 Where should I install the BSCW server software (Unix)? ..........................................................................103 9.4.3 Can I install BSCW in my 'public_html' directory on our Web server? .......................................................103 9.4.4 Why do I get a "500 Server Error" when I try to register myself? ...............................................................103 9.4.5 Why do I get an "Authentication Error" when I try to register? ..................................................................103 9.4.6 Why do I get a 'socket error' when I try and install BSCW with Irix? .........................................................104 9.4.7 Why do I get 'socket.error: Illegal seek' when I install BSCW on Linux? ....................................................104 9.4.8 Can I run BSCW with a Netscape Web server? ...........................................................................................104 9.4.9 Can I put the data files for the server on a separate disk? ...........................................................................104 9.4.10 Why does the installation of the BSCW server fail on my HP-UX machine? ............................................104 9.4.11 Why do I get a "No module named os" error? ...........................................................................................104 9.4.12 What can I do if I get a "ServiceException: getState, ()" error after "start_servers"? ..............................105 9.4.13 How can I provide user interface in different languages on our BSCW server? .......................................105 9.4.14 Why do I get a "No module named crypt" error? .......................................................................................106 9.4.15 Why do I get a "Wrong version of run-time .DLL" error? .........................................................................106 9.4.16 Why do I get "%1 is not a valid Windows application" error? ..................................................................106 9.4.17 Why do I get a "Permission denied" error from the HTTP server or BSCW? (Unix) ................................106 9.4.18 Why do I get a Python trace with "RuntimeError: cgi/bscw.cgi: No setgid"? ...........................................107 9.4.19 Why do I get an error on Windows XP, if I want to configure the IIS for BSCW? ....................................108
iii
BSCW 4.2 Administration Manual
1 How to read this Manual Before installing your BSCW server you should read at least:
the introduction to section 2 Installation of the BSCW Server (in particular section 2.2 Upgrading if you are upgrading an BSCW instance,
either section 3.2 Installation procedure for Unix or section 4 Installation procedure for Windows 2003/XP/2000/NT, depending on the operating system you are using.
This should be sufficient to install the BSCW server and carry out the initial configuration of the server. If you have problems with the installation and initial configuration process, you should read
the respective sub-section of section 3.2 or 4, depending on your operating system or Web server,
the frequently asked questions (FAQ) section 9.
In general, this should give you enough information to get your BSCW server up and running. The BSCW server is initially equipped with a license which allows usage and testing of the BSCW server for a trial period of 90 (ninety) days. After 90 days, the BSCW server is no longer usable (except for a few fundamental operations such as the upgrade license operation). Therefore, if you decide to use the BSCW server for a longer period, you need to acquire a license. The acquisition of licenses is described in section 8 BSCW License. If you have problems when upgrading your BSCW license, you should also have a look at the respective entries in the frequently asked questions in section 9. The BSCW server has a considerable number of configuration options. If you have gained some experience with usage of the BSCW system you should read section 5 to find out what configuration options are available and whether they could be used to satisfy the requirements of your users better than the default settings as specified in the code you downloaded. (For example, the default settings provide three different user profiles called Beginner, Advanced and Expert to cope with different user expertise with the BSCW system. You may adjust the respective profiles to your user groups or even define new user profiles.) In general, the administrational overhead for running a BSCW server is very low. In fact, you may install and configure your BSCW server such that you practically never need to bother with administration. Most likely, however, sooner or later you may have questions such as "How many users are registered at my server?", "How can I rename or delete a user?", or " How can I restrict the creation of workspaces?" Answers to such administrational questions can be found in section 6 Administration of BSCW Servers and in section of the frequently asked questions section.
1
BSCW 4.2 Administration Manual
2 Installation of the BSCW server As a prerequisite for installing a BSCW server you need either a computer running a Unix system the BSCW server can be installed on a large variety of Unix systems, including Solaris, SunOS, Linux, DEC OSF, HP-UX, AIX, BSD, NeXTSTEP and Mac-OS X - or a computer running Windows 2003/XP/2000/NT.
2.1
General Requirements
The hardware requirements depend largely on the number of users that are expected to use the system. In general, the hardware requirements are not particularly high. For example, a 2 GHz Pentium with 512 Megabyte RAM and 20 Gigabyte disk space should already provide a sufficient environment with satisfactory performance for about 200 users. The BSCW Server is an extension of a Web Server with the respective BSCW functionality. The extension is implemented through the CGI interface, which is supported by almost all Web servers. The BSCW software is written in Python (see the Python web site at http://www.python.org/). Therefore, besides the BSCW software, the installation of the BSCW server requires
a Web Server
a Python interpreter
(optional) extensions for Python (PyXML, Python-LDAP)
The BSCW server can be installed on a CGI 1.1 compliant Web server, e.g. Server or the Microsoft's Internet Information Server (IIS) (we recommend Server version 2.0). Python interpreters are freely available from the (http://www.python.org/). We currently support version 2.2.3 and 2.3.4 of the For performance reasons and stability we recommend version 2.3.4.
the Apache HTTP the Apache HTTP Python web site Python interpreter.
After installation the BSCW server needs to be configured. Only very few configuration efforts are required as a minimum since a few variables (e.g., the email address of the system administrator of the BSCW server) need always be set individually. The server offers a large number of configuration options but we recommend that initially a BSCW system administrator uses the default settings, except for those options which need to be configured as a minimum. The installation process is different between Unix systems and Windows 2003/XP/2000/NT (there, as usual, a self-installing executable file is provided). Therefore, the installation process for Unix and Windows 2003/XP/2000/NT is described separately in section 3.2 and section 4, respectively. You need only read one of the two sections, depending on your platform. The configuration process is to a large extent identical for Unix and Windows. Whenever a difference is necessary, this is described at the respective places in this manual. Note: Please look at the README file in the distribution and consult the frequently asked questions section in this manual - or the on-line version at http://www.bscw.de/english/faq/faq.html - for common and platform-specific installation questions; if you have a problem not addressed there, send an email to [email protected].
2.2
Upgrading to BSCW 4.2
You might skip this section if you are installing BSCW for the first time. For upgrading, you essentially proceed the same way as shown in the BSCW installation section (3.2 Unix, 4.2 2
BSCW 4.2 Administration Manual
Windows):
On Unix execute the setup script as BSCW user: # su bscw $ cd bscw-4.2.? $ python2.3 setup
On Windows execute the BSCW 4.2 installer program bscw42?.exe and select a server instance at to upgrade.
Substitute by your actual BSCW instance installation path. However, please take note of one or more of the following points which might apply to your situation: Please make a backup of your current BSCW data before you upgrade your BSCW Server. DO NOT UPGRADE If your current license is invalid (e.g. license expired, wrong host). Upgrading of BSCW with an invalid license will fail. Please obtain and install a new valid license first. Contact [email protected] for details. DO NOT UPGRADE If your license does not include free upgrades. (If you have a time-unlimited license, i.e., a license which does not expire, your license does NOT include free upgrades.) Upgrading of BSCW will invalidate your existing license key and will result in an inoperable BSCW system. Contact [email protected] for details. When upgrading from BSCW 4.2.1 or lower Attention: The SERVER_ADMINS_IP directive also restricts the user notification service (UNO)! If the SERVER_ADMINS_IP list is not empty, the IP address of the SERVER_ROOT resp. SERV_UNO_ROOT web server must be contained in this SERVER_ADMINS_IP, eg. SERVER_ADMINS_IP = [ '1.2.3.4',
# administrator IP address
'127.0.0.1',
# SERV_UNO_ROOT = 'http://localhost' or
'193.175.161.100',
# SERVER_ROOT = 'http://bscw.fit.fhg.de'
]
When upgrading from BSCW 4.1.4 or lower Important: BSCW 4.2 introduces a new owner assignment. The owner of all newly created objects automatically becomes the owner of the workspace (the owner role is now inherited by the “ambient” folder). This is in opposite to the behaviour of previous BSCW versions (< 4.2), where the creator of an object also was the owner of the object. This leads to the following effects:
Users cannot lose the access path to owned objects by accidental deletion of their workspace membership.
The quota system assigns utilised resources of all contained objects of a workspace to the owner (and not any longer to the different object creators) Attention: After the upgrade to BSCW 4.2 you should run one of the following commands to initialize all quota counters: 1. EDU licensees may only run the command bsadmin quota fix. 2. PRO licensees may run alternatively the command bsadmin quota report -vL, which 3
BSCW 4.2 Administration Manual
commits changes to the database after each user.
The actions “cut” and “delete” change the owner of an object: owner becomes the user who cut/deleted the object (the object inherits the owner of the ambient folder (who is in this case the owner of the clipboard resp. the trash)). Attention: caused by this owner change the action “destroy” always destroys objects contained in the trash. The behaviour of previous BSCW versions (< 4.2) to distribute “destroyed” objects first into the trash of the owner is omitted.
Important: BSCW 4.2 implements a new user notification service (UNO) which replaces the workspace activity report and the awareness service of previous BSCW versions. To not interfere with the new user notification service the workspace activity report configuration must be disbabled by removing the crontab (Unix) or the task scheduler (Windows) entry for bsadmin notify -a. Additionally remove the entry for AWSERV (bs_servaw) from the SERVERS list in the instance configuration file src/config.py before upgrading. After upgrading you might add an entry for bs_servuno as described in the instance configuration file comments. Important: If the LDAP package is enabled in the BSCW extension packages section (PACKAGES) of the instance configuration file, the file packages/ldap/src/config_ldap.py must be edited before upgrading:
enter the packages/ldap/src directory
save config_ldap.py to config_ldap.old
copy defaults/config_ldap.py to config_ldap.py
edit the configuation variables in the new config_ldap.py according to the old settings.
Important: The JBrowser package is no longer supported; if it is enabled in the BSCW extension packages section (PACKAGES) of the instance configuration file, remove the '../packages/JBrowser' entry before upgrading. When upgrading from BSCW 4.0.4 or lower The BSCW license server URI has been changed, be sure in /src/config.py the BSCW_LICENSE variable is set to: BSCW_LICENSE = 'http://bscw.orbiteam.de/pub'
Important: Starting with BSCW 4.0.6 a new license mechanism was introduced. The new mechanism does not longer bind the license to the BSCW servers IP address and installation path. It is name based, which means you have to define in /src/config.py the SERVER_ROOT variable before applying for a license (cf. section 3.3.2 for Unix or 4.5.1 for Windows) When upgrading from BSCW 3.4.1 or lower: Important: Since version 4.0 BSCW uses roles for access control. This new approach is incompatible with the older access control model. All special access control settings are reset to (hopefully reasonable) defaults during upgrade. Starting with BSCW 4.0 the document tree layout of the BSCW server has been changed; if you use the Apache HTTP server, please adopt your configuration to the new layout as given in /apache.conf (cf. section 3.3.1 for Unix or 4.5.2 or 4.5.3 for Windows). The archive function changed internally. It now descends the directories recursively. If you use the zip archiver, please add the parameter -r in the archivers definition in
BSCW 4.2 Administration Manual path>/src/config_convert.py, e.g. # Zip/WinZip ('application/zip', '/usr/local/bin/zip -r %(dest)s %(src)s [D_NAME=%(dest)s.zip]', '/usr/local/bin/unzip %(src)s'),
When upgrading from BSCW 3.4.3 or lower: Important: Fix the BSCW archive extract security vulnerability as described in http://bscw.fit.fraunhofer.de/Bulletins/BSCW-SB-2001-08.extract.txt by exchanging the extract function tar xf with the BSCW untar -xS extractor. Best upgrade
to at least version BSCW 3.4.4. When upgrading from BSCW 3.2 or 3.3: Important: During upgrade from BSCW 3.2 or 3.3 your current BSCW license becomes invalid and a new evaluation license for BSCW 4.2 will be installed. It will be valid for 90 days and 200 users. This might be a problem, if you have already more than 199 registered BSCW users, because new users cannot (be) register(ed) anymore. We recommend upgrading your license to the new release as soon as possible. If your old license includes support and upgrading, you will get the new license at no cost (see BSCW license in section 8). Note: New packages (e.g. SWISHPPindex, ldap) are not automatically enabled after upgrading. You have to add the package directories to the PACKAGES list in the server settings of the [Options --> Admin]-page or the file /src/config.py. Some of the packages also need installation of extra software and configuration. For details, please consult the README files in the respective package directory. When upgrading from BSCW 2.2 or lower: Execute the following commands in your existing BSCW2 instance directory before installing the new version: $ cd $ start_servers –k $ mkdir data $ mv src/.htpasswd data/htpasswd $ mv src/BSCW_Store data/Store $ mv src/BSCW_Files data/Files $ echo > src/config.py
Then do the BSCW installation and reconfiguration of your HTTP server as described in the subsequent section 3.2 for Unix or section 4 for Windows. Note: You may not replace the upgraded BSCW server instance configuration file (/src/config.py) by a config.py file of a previous BSCW version! Instead the upgraded BSCW server instance configuration file must be edited manually. Note: Since the Apache HTTP Server configuration /apache.conf is automatically generated all manual changes will be lost after an upgrade.
5
BSCW 4.2 Administration Manual
3 Installation procedure for Unix These are the installation instructions for BSCW 4.2 on Unix machines. They apply to new installations of the server and for users upgrading from an existing BSCW server.
3.1
System requirements
The BSCW server is written in Python. To install the system you need a Python interpreter (version 2.3.4) for your Unix platform. The Python implementation is copyrighted, but is freely usable and can be downloaded from the Python web site (http://www.python.org/). Note: BSCW needs Pythons' crypt module. On some systems, this module is not installed by default. Hence, if you get a “No module named crypt” error, you have to enable the crypt module in Modules/Setup and rebuild Python. Additionally you require a C compiler (gcc) to compile a binary wrapper (on systems which do not allow execution of set-group-id scripts, e.g. Linux) and a CGI 1.1 compliant Web server - we recommend the Apache HTTP Server 2.0 (http://httpd.apache.org/). The BSCW server software distribution is available as a TAR archive BSCW4.2.?.tar.gz (gzip'ed tar file)
The name of the download file contains the version number – e.g. BSCW4.2.1.tar.gz contains BSCW version 4.2.1. Please make sure to install the latest version of BSCW and always provide your version number when contacting support staff. There may be additional patch releases available after the latest release – check FIT's home page of the BSCW Project http://bscw.fit.fraunhofer.de/ or the BSCW Product home page http://www.bscw.de/ for latest updates that have been released for download.
3.2
Installation
The installation program of the BSCW software must be run as a normal user (e.g. under your user ID, or a special BSCW user ID). We strongly recommend to create a special BSCW system administrator user ID bscw with an own group ID bscw, e.g. execute as superuser # groupadd bscw # useradd -g bscw bscw
It does not matter where you install BSCW, but the host machine of your HTTP server you wish to use for BSCW must have access to the file system where BSCW is installed. For best performance put BSCW on a file system local to the host where your HTTP server runs. If you don't have write-access to a proper place, ask your system administrator to create a directory for your BSCW installation and to change the ownership and access as follows (as superuser): # mkdir # chown bscw # chgrp bscw # chmod 755
6
BSCW 4.2 Administration Manual
However the BSCW directory should not be accessible via the DocumentRoot or any other alias directives of your HTTP server. The path to the BSCW directory needs only “search permission” for the user/group ID that the HTTP server uses. The BSCW server is excecuted with the group ID bscw, which is the primary group ID of the BSCW system administrator user ID. The set-group-id bit of the BSCW CGI scripts invoked by your HTTP server set this group ID automatically. Hence access rights for the group ID bscw will be inherited during execution of all BSCW CGI scripts. To ensure an error free operation of the BSCW server: the set-group-id bit of the BSCW CGI scripts has to be set (which is done automatically done by the BSCW setup procedure (see below))
the BSCW directory (and all files and directories below) should belong the group ID bscw
the file system of the BSCW directory must not be mounted with the nosuid option
If the set-group-id execution of the BSCW CGI script fails you will get an “Error: Wrong group id“ while BSCW operation. To fix this problem see the “note” in the last paragraph of section 3.3.3 Change your current user ID to the BSCW user ID bscw and decompress/extract the BSCW software from the distribution archive (use the tar p option to restore the original file modes of the archive!) # su bscw $ cd $ gunzip < bscw-4.2.?.tar.gz | tar xpf -
This will create the distribution directory /bscw-4.2.?/ which contains the following files and directories: BSCW_COPYRIGHT
Copyright and license information
MD5-dist
MD5 signatures of delivered BSCW software
README
Readme
doumentation/
Administraton manual
keep_me
A list of filenames (patterns) which should not be overwritten during install (see below)
messages/
Language dependent message files
packages/
extension packages for BSCW server
pyc??/
Modules compiled for Python version ?.?
release
Release date
resources/
Icons, Styles, Java applets etc.
setup
The installation script
src/
BSCW Python sources and modules
src/admin/
BSCW administration modules
src/converters/
Converter scripts / programs
src/defaults/
Default BSCW configuration files
src/http/
Experimental http server
src-aux/
"patched" Python modules etc.
start_servers
script to start/stop the BSCW database server
7
BSCW 4.2 Administration Manual
If you are upgrading an existing BSCW server please also read the section 2.2 Upgrading to BSCW 4.2. To install BSCW 4.2, enter the distribution directory /bscw-4.2.?/ and execute the following commands (with the user ID bscw; not as superuser): $ cd /bscw-4.2.? $ python2.3 setup
(If you omit the BSCW , the default value ../server is used as BSCW instance directory.) The setup command will then install the BSCW server in the instance directory. After successful installation the BSCW server is automatically started. Note: If you use python setup the installed Python interpreter with is used for your BSCW instance. To specify the Python interpreter with version number allows you to use simultaneously multiple versions of Python. Note: If the BSCW server does not start up properly, see the file BSCW log file /data/bscw.log for details and error messages. The frequently asked questions (FAQ) list (http://www.bscw.de/english/faq/faq.html) might also be helpful.
3.3
Configuration
The configuration includes the configuration of your Web server and the configuration of the BSCW server. Furthermore, the registration of the server administrator should be considered part of the initial configuration process.
3.3.1
HTTP server configuration
For the Apache HTTP server (version 2.0 (resp. 1.3)), the setup process has automatically generated a configuration file /apache.conf, which contains all necessary configuration instructions. We recommend including the contents of this file into your Apache HTTP servers configuration file httpd.conf (into the main server or corresponding virtual server definition) with the directive: Include /apache.conf
You may change the BSCW Apache configuration file by using the bsadmin conf_apache script. To adopt the generated Apache configuration file to your local web server settings use one of the following options:
If no option is used then bsadmin conf_apache tries to read the old option setting from apache.conf (if it exists). Use option -n or remove apache.conf if you want to avoid this.
If the option -r is used then the apache module “rewrite” will be loaded and is configured in such a way, that the authentication is handled by the BSCW server. (On Windows this is the default case).
If the option -g is used then global module includes are written into an extra file apache_glob.conf. This might be necessary if apache.conf is included in a virtual host segment.
If the option -s is used then the apache server is configured for autentication via client certificates. This option includes the -r option and requires to include the apache.conf file in an SSL enabled server.
8
BSCW 4.2 Administration Manual
Note: The LoadModule directives (as given in apache.conf) do not work within a ... section. Please ensure to load the necessary additional modules (cgi_module, headers_module, rewrite_module) within the “Section 1: Global Environment” of the Apache HTTP server httpd.conf file. Remember to restart always your Apache HTTP server if the apache.conf file was altered. Please note the following relations between HTTP server directives and the BSCW server instance configuration file (/src/config.py) variable settings:
the BSCW server instance SERVER_ROOT definition must correspond at least with one (virtual) server name (as specified in the ServerName directive), e.g.: SERVER_ROOT = 'https://bscw.domain.org' ⇔ ServerName “bscw.domain.org” Port 443
the BSCW server instance value for the BSCW_REALM variable corresponds with the setting of the HTTP servers AuthType and AuthName directives, e.g.: BSCW_REALM = 'Basic realm="BSCW Shared Workspace Server"' ⇔ AuthType = Basic AuthName = "BSCW Shared Workspace Server"
Otherwise problems with user authentication might occur: typically, users are asked twice for their passwords during registration or when switching user id. Apache HTTP Security Advisory: Over the last months several security problems have been discovered in the server source code and in third-party code that many websites rely on. Some of these problems are now being actively exploited on the Internet
If you are running an SSL-enabled Web server using OpenSSL, upgrade to at least version 0.9.6m or 0.9.7e of OpenSSL and recompile all applications that use OpenSSL.
Upgrade your Apache HTTP Server to version 2.0.52 (or 1.3.33) or higher.
3.3.2
BSCW instance configuration
You might skip the next parts of the configuration if you just upgraded your old BSCW server. The old configuration should be OK. Local configuration details of your BSCW instance are held in the configuration file at /src/config.py (cf. section 5.1). The minimum you need to do is to configure “Section 1: MANDATORY server settings” of this file:
The “server root” - the hostname (and port) part of your BSCW servers URL - is specified in the variable SERVER_ROOT contains the absolute URL of your BSCW server and an optional port. If no port is specified the standard ports 80 (for HTTP) or 443 (for HTTPS) are assumed: SERVER_ROOT = 'http://bscw.domain.org/' SERVER_ROOT = 'http://bscw.domain.org:123/' SERVER_ROOT = 'https://bscw.domain.org/'
A fully qualified host name is required as server name “bscw.domain.org”, in order to allow the BSCW server to resolve its name to an IP address (SERVER_ROOT may not contain an IP address 9
BSCW 4.2 Administration Manual
anymore!). Ideally you define a host name/nickname (A/CNAME) in your DNS zone, which points to your BSCW server host, e.g. server1.domain.org
A
1.2.3.4
server2.domain.org
A
1.2.3.5
bscw.domain.org
CNAME
server1.domain.org
Proceeding this way a future migration of your BSCW server from server1 to server2 will keep the well known URL http://bscw.domain.org/ and your license will not be invalidated by the migration.
SERVER_ADMIN contains the valid email address of the server administrator, e.g. SERVER_ADMIN = '[email protected]'
SERVER_ADMINS defines a list of BSCW users that have administrator rights, e.g. SERVER_ADMINS = [ 'admin', 'YourName' ]
You will most likely want to add your (future) BSCW login name to SERVER_ADMINS to give yourself administrator rights (and maybe the login names of other BSCW users who should have admin rights).
SMTP_HOST contains a host name or an IP-address of a mail host, that accepts mail posting by
SMTP, e.g. SMTP_HOST = 'mail.domain.org'
The BSCW system can use the local mail transfer agent (MTA), such as sendmail to send email (e.g. registration invitations), which should be fine for most installations. However, it may be better if BSCW directly uses your smart mailhost via SMTP. In general we recommend to use SMTP_HOST rather than SENDMAIL. To do this, set the SMTP_HOST directive in config.py to the IP address (or fully qualified domain name) of the machine that hosts your smart mailhost (resp. MTA). Note: if you you are using MS Exchange as MTA, you must explicity allow the IP address of you BSCW server host to relay email. Do not restrict now in “Section 3: Server access” of the configuration file the registration process by setting MAY_REGISTER to your future name (for instance). You would not be able to register yourself! Set this field after registering yourself, as described in the next section.
3.3.3
Administrator account registration
After configuration of “Section 1: MANDATORY server settings” of your BSCW instance configuration file (/src/config.py), you have to register yourself as administrator: open your Web browser with the following URL: http://bscw.domain.org/pub/bscw.cgi?op=rmail
This will open the user registration form. Follow the given instructions and complete your user registration. After submitting the form an authentication mail is sent to the given mail address. Open the mentioned link within this mail to complete your registration by defining your login name “YourName” and password (mind login name and password are case sensitive!). For security reasons the given URL in the authentication mail will only work one time; if you should fail to register please repeat the self-registration. After completing your self-registration enter your login name into the SERVER_ADMINS list of the 10
Now you may login by opening the URL: http://bscw.domain.org/bscw/bscw.cgi
with your login name “YourName” and your password. If you open the URL http://bscw.domain.org/pub/
you get a BSCW overview/index page which contains links to this registration URLs of your BSCW instance. Note: If you get an “Error: Wrong group id” during this steps the BSCW CGI scripts are not executed with the group ID bscw. This may happen, because of three reasons: 1. The set-group-id bit of the BSCW CGI script is not set. In this case, please execute the following command in your BSCW instance directory: $ cd $ ./bsadmin chkconfig
2. You have installed BSCW on a file system that is mounted with the nosuid option. In this case you have to remount the filesystem without the nosuid option. 3. Your operating system does not support the set-group-id bit for scripts (eg. Linux, BSD). In this case you have to compile a binary wrapper program and to reinstall the CGI scripts. Please execute the following commands in your BSCW instance directory: $ cd $ cc -o wrapper wrapper.c $./bsadmin chkconfig
3.4
Database Server, Garbage Collection and Backup
All data of the BSCW server is held in the BSCW data store and handled through the BSCW database server. The BSCW database server is managed with the start_servers script, which is located in the BSCW instance directory :
to start up BSCW database server use $ /start_servers
to stop BSCW database server use $ /start_servers -k
to run the garbage collector use $ /start_servers -gc
The state and errors of the BSCW database server are logged in the file /data/bscw.log. We recommend that start_servers should be executed at system boot and start_servers -k at shutdown. To achieve this you have to install on a SYSV Unix an init.d boot script or on a BSD Unix an rc.d (resp. rc.local) boot script, which utilizes the start_servers script, for example: #!/bin/sh BSCWDIR=
11
BSCW 4.2 Administration Manual case $1 in 'start') echo "Starting BSCW daemon" if [ -x $BSCWDIR/start_servers ]; then $BSCWDIR/start_servers fi ;; 'stop') echo "Stopping BSCW daemon" if [ -x $BSCWDIR/start_servers ]; then $BSCWDIR/start_servers -k fi ;; esac
You will need to set up the system to garbage collect every day. The task of the garbage collector is to find unreferenced, e.g., obsolete objects in the data store and remove them. For performance reasons, a “delete” operation on an object may not remove the respective object physically from the store. If you do not run the garbage collector periodically, the BSCW data store will grow constantly although many of its objects are obsolete. This would waste disk space and may substantially reduce the performance of the BSCW server. We recommend that you set up a cron job for running the start_servers -gc script, though you can do it manually. An example crontab entry for daily garbage collection at 06:05 looks like: # garbage collection 5 6 * * * /start_servers -gc
Do not stop the BSCW database server before garbage collection, the garbage collection needs a running server! Additionally it is urgently recommended to have regular BACKUPS (e.g. daily) of the configuration and the data store to avoid loss of data, e.g., because of a disk crash. The recommended time for backup is just after garbage collection. The garbage collection creates alternating a garbage collected version of the BSCW database in the files /data/StoreA or /data/StoreB (Note: these locations can be overridden by editing /src/config.py). Generally you should consider the following files or directories of your BSCW instance (relative to your ) for backup:
BSCW instance configuration files (only if altered by the BSCW administrator) /src/config.py /src/config_cal.py /src/config_convert.py /src/config_html_ui.py /src/config_icon.py /src/config_meet.py /src/config_mime.py /src/config_mpick.py /src/config_msg.py
12
BSCW 4.2 Administration Manual
BSCW instance data files and directories /data/Backup /data/Files/ /data/htpasswd
Backup of the instance data files and directories can be done automatically after garbage collection if there is a file start_servers.conf in the instance directory containing the following: save=’<safe-path>/bscw_backup.tar.gz’ backup_files=`./bsadmin getconfig SAVE FILES PASSWD` backup=’tar cf - $backup_files | gzip -c > $save && rm `./bsadmin getconfig SAVE`’
(The file start_servers.conf is “sourced” by the start_servers script and $backup is evaluated after successful garbage collection.) Using this hook the whole state is saved to the file <safe-path>/bscw_backup.tar.gz. To restore the system state from such a backup, make sure you stop the BSCW database server and then do the following: $ cd $ ./start_servers -k $ cd / $ gunzip < $save | tar xpf $ cd $ mv `./bsadmin getconfig SAVE RESTORE` $ ./start_servers
(Which restores the BSCW instance data files and directories and moves the (restored) /data/Backup path>/data/StoreA or /data/StoreB.)
3.5
BSCW Services
This section contains instructions on how to configure the additional services provided for the BSCW shared workspace system. Configuration has to be done either in the BSCW instance configuration file (/src/config.py) or on operating system level (e.g. crontab). Special Python modules or Java components provide these optional services. The following services are currently supported:
Indexing / Document Contents Search
Folder Mail Delivery
3.5.1
Indexing / Document Contents Search
For Unix systems, the BSCW package SWISHPPindex might be used as an adapter to the search and indexing system SWISH++ written by Paul J. Lucas. The SWISH++ software is available under the terms of the GNU General Public License but is not delivered with the BSCW system. You have to install and configure SWISH++ (preferably in the directory /packages/SWISHPPindex) before you can enable the SWISHPPindex package in /src/config.py. 13
BSCW 4.2 Administration Manual
As far as we know, the SWISHPPindex package does work with SWISH++ versions 4.8 up to 6.0. Please consult the file packages/SWISHPPindex/README and the documentation of SWISH++ for updated and further information. The following installation instructions are only a short guideline, because the URL and versions of the SWISH++ software might change independently of the BSCW software. Installation (substitute by 4.8, ..., 6.0 accordingly): 1. Go to the directory /packages/SWISHPPindex 2. Download the swish++-.tar.gz archive from the URL http://homepage.mac.com/pauljlucas/software/swish/
to the SWISHPPindex directory. If the URL does not work, please check the README file in the SWISHPPindex for a more actual reference or try a common search engine on the Web looking for e.g. "SWISH++". 3. Unpack the sources. $ gunzip < swish++-.tar.gz | tar xf -
4. Go to the swish++- subdirectory, configure and run make $ cd swish++- $ make
Note: For details please have a look at the README and INSTALL.unix files in this directory; you have to edit config.h, config/config.mk respectively. Note: On SuSE Linux the gcc (version 3.3.1) optimizer seems to be broken: if the index program causes segmentation faults remove the optimization -O2 flag from the OPTIM macro in config/config.mk and recomplie 5. Copy the compiled programs into the package directory: $ cp search
/packages/SWISHPPindex
$ cp index
/packages/SWISHPPindex
$ cp extract
/packages/SWISHPPindex
Note: alternatively you may also link the compiled programs into the package directory. 6. Copy the file swish++-.conf to swish++.conf. $ cd /packages/SWISHPPindex $ cp swish++-.conf swish++.conf
7. Adapt swish++.conf to your needs. Especially, check the paths of the filter programs. They might not work on your system. Note: The runtime value the WordThreshold setting in the swisch++.conf file must be equal or lower to the compile time value of WordThreshold_Default from the config.h file, otherwise only the super-user may execute the index program. Note: Starting with version 6.0 Swish++ supports “near” searches. Using this feature approximately doubles the size of the generated index file and significantly slows down the indexing process. So it might be advisable to turn off “near” searches by setting StoreWordPositions to no in the swish++.conf file.
14
BSCW 4.2 Administration Manual
8. Enable the SWISHPPindex package, i.e. add “../packages/SWISHPPindex” to the PACKAGES list in /src/config.py After successful installation, you might try the first index creation: $ cd $ ./bsadmin create_index
We recommend invoking the indexer regularly via a crontab entry like 12 1 * * * /bsadmin create_index >/dev/null 2>&1
IMPORTANT NOTE: (applies only if your system was upgraded from a BSCW version prior to 3.4) The index program ignores files without extensions. New files in your BSCW 4.2 system are always created with an extension defined by the MIME-type of the BSCW document. When you are upgrading from an older BSCW version the BSCW files don't have any extension set and they are not automatically renamed during upgrade. Hence all old files created before upgrading are not indexed. In order to get old files renamed, you must execute $ bsadmin chkfiles -e
This command will create extensions for all BSCW files according to the MIME-type configuration.
3.5.2
Folder Mail Delivery
Sending email to a BSCW folder is an alternative to the usual HTML/HTTP interface where users create content, e.g., via “Add Document” or “Add Note” actions using a Web browser. To enable folder mail delivery the following configuration steps have to take part:
the BSCW mail delivery agent (MDA) has to be configured
the local mail transfer agent (MTA) mail has to be configured to deliver incoming mails for the BSCW server mailbox to the BSCW MDA
to extract multipart email messages a converter for the MIME type “message/rfc822” has to be defined.
Note: Your MTA must support VERP (variable envelope return paths) to allow the individual addressing of single folders; BSCW folder delivery is known to work with recent versions of sendmail, Postfix and qmail). BSCW mail delivery agent (MDA) The BSCW mail delivery agent (MDA) is configured by setting the following entries in the BSCW server instance configuration file /src/config.py: #
MDA_MTA
#
Specifies the local mail transfer agent (MTA), currently
#
supported are:
#
MDA_A = 'qmail'
#
MDA_MTA = 'sendmail'
#
Setting MDA_MTA = ''
or any unknown MTA will disable the
#
BSCW mail delivery feature (this is the default).
15
BSCW 4.2 Administration Manual #
MDA_MBOX
#
Local mailbox name for BSCW mda (this is normally the BSCW
#
user id name)
#
MDA_DOMAIN
#
Domain name of the BSCW MDA (which is the delivery domain of
#
the local MTA for the local BSCW MDA mailbox)
#
MDA_LOGLEVEL
#
BSCW mail deliver agent loglevel:
#
0
#
-
#
9
#
everything and even more is logged
MDA_LOGFILE
# #
only fatal errors are logged
Specifies the BSCW mail deliver agent logfile MDA_HDRDESCR
#
Defines which headers are shown in the description of an uploaded
In the given example, the local BSCW mailbox is set to “bscw” and the delivery domain name of the local MTA is “domain.org”. Hence, a folder mail address has the form “[email protected]” (for sendmail) and “[email protected]” (for qmail). To ensure consistent mail addresses, when local BSCW mail delivery is enabled, the BSCW server should only use the local mail server, therefore it is advisable to set SMTP_HOST = ''
Local Mail Transfer Agent (MTA) To deliver mail into a BSCW folder the localhost mail transfer agent has to deliver mail messages to a “program”, namely to the BSCW mail deliver agent. This is achieved by “piping” the message into the BSCW main CGI script: "|/cgi/bscw.cgi"
Sendmail To enable the BSCW MDA to deliver mails into folder for sendmail the following /etc/mail/sendmail.cf configuration must be ensured:
to allow sendmail program message delivery to the BSCW MDA the sendmail “prog” mailer has to be defined in /etc/mail/sendmail.cf as follows: Mprog,
The F and P flags in the “prog” mailer flag list F= are required, to ensure the message contains a “From:” and “Return-Path:” header line. Note: you may not use “smrsh” (restricted shell for sendmail) as “prog” mailer for sendmail, since it does not permit the delivery into the BSCW MDA script.
to enable the BSCW MDA to determine a well-defined recipient of a message you have to ensure the header definition HReceived in /etc/mail/sendmail.cf contains a for $u; $|;
line (which is the default setting in newer sendmail versions). After editing /etc/mail/sendmail.cf your sendmail needs to be restarted before changes become effective. After successful sendmail configuration, the program delivery to the BSCW MDA is enabled by choosing one of the following alternatives:
enter the following line into BSCW users ID $HOME/.forward file: "|/cgi/bscw.cgi"
or
add an alias to the sendmail aliases database /etc/aliases file bscw:"|/cgi/bscw.cgi"
and run the “newaliases” program. Finally to enable folder mail delivery in BSCW set in the BSCW server instance configuration file /src/config.py (beside the other settings described above) MDA_MTA = 'sendmail'
To test the folder mail delivery create a folder (within BSCW) and trigger the action “Open to Mail”. Choose in the form the “enabled for anybody” option. After enabling the mail upload look at the folders info page to determine the folders email address. (If in the “Details” table a “Email address” row is missing, the BSCW MDA was not properly configured, check again your BSCW MDA configuration in the BSCW server instance configuration file /src/config.py). Increase the loglevel of the BSCW MDA by setting MDA_LOGLEVEL = 8
in /src/config.py. Send a mail message to the prepared folder address and check in /var/log/syslog (or wherever your sendmail writes its log entries) if the local sendmail program received the message and delivered it to the BSCW MDA. Typical log entries of a successful delivery look like: Oct
Next check your MDA_LOGFILE (default: /data/MdaLog). A successful delivery log entry for a sendmail MTA at loglevel 8) looks like: 02-10-07 18:00:21 Info [8] loglevel is 8 02-10-07 18:00:21 Info [7] invoked as 523/57 02-10-07 18:00:21 Info [8] MDA_MTA
= 'sendmail'
MDA_MBOX
= 'bscw'
MDA_DOMAIN = 'bscw.de' 02-10-07 18:00:21 Info [8] sender addr in 'return-path:' header. 02-10-07 18:00:21 Info [7] recipient in header: 02-10-07 18:00:21 Info [4] msg for Folder#38241 (access 'anybody'); 02-10-07 18:00:21 Info [3] msg from
02-10-07 18:00:21 Info [6] msg owner is 'hinrichs' (container owner)
Postfix To enable the BSCW MDA to deliver mails into folders for the Postfix MTA follow the given instructions for sendmail except for the /etc/mail/sendmail.cf configuration. Instead add the line recipient_delimiter = -
to the Postfix configuration file /etc/postfix/main.cf. Qmail To
assign
a
local
BSCW
user
mailbox,
enter
the
following
lines
into
your
/
var/qmail/users/assign file =::::::: +-:::::-::
where = local BSCW server mailbox, e.g. bscw = user name of the BSCW server user, e.g. bscw = user ID of the BSCW server user, e.g. 523 = group ID of the BSCW server user, e.g. 57 = path to your BSCW instance, e.g. /opt/bscw/BSCW42
While the configuration line starting with a = character defines the handling of the local address bscw, the line starting with a + character handles all extension addresses bscw-* (for further details consult the qmail-users man page or the “Life with qmail” documentation). After changing the contents of the /var/qmail/users/assign file you have to run the qmail-newu command to update the assignments database. To enable BSCW MDA program delivery for all extension addresses bscw-*, create the file /.qmail-default (with the BSCW user ID and group ID as owner) and enter one single line |/cgi/bscw.cgi
Finally set in the BSCW server instance configuration /src/config.py (beside the other settings described above)
18
BSCW 4.2 Administration Manual MDA_MTA = 'qmail'
To test the folder mail delivery create a folder (within BSCW) and trigger the action “Open to Mail”. Choose in the form the “enabled for anybody” option. After enabling the mail upload look at the folders info page to determine the folders email address. (If in the “Details” table a “Email address” row is missing, the BSCW MDA was not properly configured, check again your BSCW MDA configuration in the BSCW server instance configuration file /src/config.py). Increase the loglevel of the BSCW MDA by setting MDA_LOGLEVEL = 8
in /src/config.py. Send a mail message to the prepared folder address and check in /var/log/syslog (or wherever your qmail-send writes its log entries). if the qmail-send program delivered it to the BSCW MDA. Typical (sys)log entries of a successful delivery look like: Sep 19 15:39:16 maestral qmail: [ID 748625 mail.info] 1029764356.914648 new msg 236165 Sep 19 15:39:16 maestral qmail: [ID 748625 mail.info] 1029764356.914769 info msg 236165: bytes 653 from <[email protected]> qp 4281 uid 503 Sep 19 15:39:16 maestral qmail: [ID 748625 mail.info] 1029764356.915894 starting delivery 22: msg 236165 to local [email protected] Sep 19 15:39:16 maestral qmail: [ID 748625 mail.info] 1029764356.916318 status: local 1/10 remote 0/20 Sep 19 15:39:17 maestral qmail: [ID 748625 mail.info] 1029764357.554749 delivery 22: success: did_0+0+1/ Sep 19 15:39:17 maestral qmail: [ID 748625 mail.info] 1029764357.555183 status: local 0/10 remote 0/20 Sep 19 15:39:17 maestral qmail: [ID 748625 mail.info] 1029764357.555524 end msg 236165
Check your MDA_LOGFILE (default: /data/MdaLog). A successful delivery log entry for a qmail MTA at loglevel 8) looks like: 02-09-19 15:39:16 Info [8] loglevel is 8 02-09-19 15:39:16 Info [7] invoked as 523/57 02-09-19 15:39:16 Info [8] MDA_MTA
= 'qmail'
MDA_MBOX
= 'bscw'
MDA_DOMAIN = 'bscw.de' 02-09-19 15:39:16 Info [8] sender addr in 'return-path:' header. 02-09-19 15:39:16 Info [4] msg for Folder#2397 (access 'anybody'); 02-09-19 15:39:16 Info [3] msg from
02-09-19 15:39:16 Info [6] msg owner is 'paulsen' (container owner).
Multipart email message extraction In order to extract attachments of uploaded multipart email messages into the clipboard an additional archiver for the MIME type “message/rfc822” has to be defined in the converter configuration file
BSCW 4.2 Administration Manual Archivers = [ # ... # RFC822 ('message/rfc822', 'internal', 'internal'), ]
20
BSCW 4.2 Administration Manual
4 Installation procedure for Windows 2003/XP/2000/NT These are the installation instructions for BSCW 4.2 on Windows 2003/XP/2000/NT machines. If you upgrade from a previous version of the BSCW server, read also the upgrade instructions below. Please follow the steps described in the section 4.5.5 below if you want to de-install the server.
4.1
System requirements
The BSCW server requires the following from your Windows 2003/XP/2000/NT installation:
A PC (e.g. Pentium 4, 2,3 GHz)
512MB RAM recommended (256MB RAM minimum)
Windows 2003/XP/2000 with Microsoft Internet Information Server (IIS5/IIS6) or Windows NT Server 4.0, Service Pack 4 (or higher) with Microsoft Internet Information Server (IIS4) or Windows 2003/XP/2000 or Windows NT 4.0, Service Pack 4 (or higher) with Apache HTTP Server 2.0 for Windows 2003/XP/2000/NT
Python 2.3.4
Win32 Extensions for Python and Pyhtonwin
Access to a SMTP daemon (Unix or Windows based)
The Windows NT 4.0 Service Pack 4 includes a number of bug fixes for your Windows NT Server 4.0. The Microsoft Internet Information Server, Version 4 (IIS4) can be installed with the Windows NT 4.0 Option Pack. An overview about the service packs can be found at
http://www.microsoft.com/ntserver/nts/downloads/
Python 2.3.4 and the Win32 Extensions for Python are copyrighted, but freely usable and can be downloaded from
http://www.python.org/
http://sourceforge.net/projects/pywin32/
Additionally you require a CGI 1.1 compliant Web server. The BSCW server supports
Microsoft Internet Information Server
Apache HTTP Server 2.0
The Apache HTTP Server implementation is copyrighted, but is freely usable and can be downloaded from the Apache HTTP Server Project (http://httpd.apache.org/).
4.2
Installation and Configuration
Ensure the Web server and Python and its Win32 Extensions are properly installed on your machine. The BSCW server sources are available as a self-extracting archive: bscw42?.exe The name of the download file contains the version number – e.g. bscw421.exe contains BSCW version 4.2.1. Please make sure to install the latest version of BSCW and always provide your 21
BSCW 4.2 Administration Manual
version number when contacting support staff. There may be additional patches available after the latest release – check FIT's home page of the BSCW Project http://bscw.fit.fraunhofer.de/ or the BSCW Product home page http://www.bscw.de/ for latest updates that have been released for download. Download the archive. Exit all applications including Python and the BSCW server (if you already have a BSCW installation). Double click on bscw42?.exe to start the installer and then follow the instructions. During installation you have to specify: 1. The BSCW directory location and the BSCW database server port. Please enter a directory location (e.g. C:\BSCW\server) for your BSCW server installation path and a port number (e.g. 12968).
2. The IP address (or fully qualified domain name) of the machine hosting your mail transfer agent (MTA) resp. smart mailhost to use for outgoing mail (e. g. mail.domain.org) and the “server root” (the host (and port) part of your BSCW servers URL) of your BSCW server. While a working MTA is mandatory for your BSCW server operation, you may define the your BSCW “server root” later, see section 4.5.1 Note: if you you are using MS Exchange as MTA, you must explicity allow the IP address of you BSCW server host to relay email.
3. A valid BSCW server administrator email address and a (comma separated) list of user names who subsequently (after their user registration, see below administrator registration) shall become a BSCW server administrator. 22
BSCW 4.2 Administration Manual
4. The virtual directories in the BSCW Web server document tree. You only need to specify alternate directories when you install more than one BSCW server instances on the same (virtual) BSCW Web server, otherwise you should keep the provided default values:
After installation the BSCW server starts automatically. Depending on the deployed HTTP server, you have to do the following configuration alternatives:
Microsoft Internet Information Server (IIS) If you use the Microsoft Internet Information Server (IIS) all necessary IIS configuration for BSCW is done by the setup script automatically. No further action is required to configure the HTTP server. Finally the setup script launches your default Web browser to connect to your BSCW server.
Apache HTTP Server If you use the Apache HTTP Server (version 2.0) the setup process has automatically generated a configuration file /apache.conf, which contains all necessary configuration instructions. We recommend including the contents of this file into your Apache HTTP servers configuration file httpd.conf (into the main server or corresponding virtual server definition) with the directive: Include /apache.conf
(For a more complete Apache HTTP Server configuration discussion see the corresponding configuration section 4.5.3) After the BSCW server is started for the first time, you have to register yourself as administrator. In a Web browser open the URL: 23
This will open the user registration form. Follow the given instructions and complete your user registration. After submitting the form an authentication email is sent to the given mail address. Open the mentioned link within this email and complete your registration by defining your login name and password. Enter as login name one of the in the installation procedure step 3 (see above) entered administrator user names (mind login name and password are case sensitive!). Now you may login by opening the URL: http://[:port]/bscw/bscw.cgi (e.g. http://bscw.domain.org/bscw/bscw.cgi)
If you open the URL http://[:port]/pub/ (e.g. http://bscw.domain.org/pub/)
you get a BSCW overview/index page which contains links to this registration URLs of your BSCW instance. If you upgrade from a previous BSCW version to BSCW 4.2, the installation program will read some of your settings out of your registry during the installation dialogue. Also the database will be converted automatically into the BSCW 4.2 format.
4.3
Database Server and Garbage Collection
All data of the BSCW server is held in the BSCW data store and handled through the BSCW database server. The BSCW database server is managed with the bsadmin script, which is located in the BSCW instance directory . The BSCW server can be administered by executing the bsadmin script from a DOS shell as follows: > cd > bsadmin start
Starts the BSCW server. > bsadmin stop
Stops the BSCW server. > bsadmin garbage
Runs the garbage collection on the BSCW database. Note the garbage collection requires the BSCW server to run! > bsadmin
Lists further administration functions. We recommend that bsadmin start should be executed at system boot. To achieve this you have to configure your task scheduler so that the BSCW servers starts automatically during system boot. Furthermore, for the garbage collection a task job must be set up, which calls these functions periodically (see below).
24
BSCW 4.2 Administration Manual
It is strongly recommended to garbage collect on a daily basis. The task of the garbage collector is to find unreferenced, e.g., obsolete objects in the data store and remove them. For performance reasons, a "delete" operation on an object may not remove the respective object physically from the store. If you do not run the garbage collector periodically, the BSCW data store will grow constantly although many of its objects are obsolete. This would waste disk space and may substantially reduce the performance of the BSCW server.
4.4
Task Scheduler
On Windows 2003/XP/2000/NT use the task scheduler to configure the automatic start of BSCW and to schedule periodic system commands (such as the garbage collection or the email notification). The task scheduler is included in Windows 2003/XP/2000 – on NT it is an add-on to the Internet Explorer 4 (or higher) and can be installed online if you connect with your Internet Explorer 4 to the page: http://www.microsoft.com/windows/ie/download/ It provides a convenient way to launch automatically the BSCW server and garbage collector in the background without showing an DOS shell. At least you have to schedule two jobs, one to start the BSCW server during system start-up and one to run the BSCW garbage collector (e.g. once per night).
Use one of the following command lines for the scheduled jobs: "\bsadmin.bat" start "\bsadmin.bat" garbage
You can use the commands above without the quotes if the path names do not contain any spaces. Important: the task scheduler requires bsadmin.bat. If you use only bsadmin it won't work. There should not be any problems if you shut down your machine without explicitly stopping the BSCW server first. Note: Do not run the same BSCW server instance more than once! This can seriously damage the BSCW database.
25
BSCW 4.2 Administration Manual
4.5
Further Configuration Details
All BSCW configuration parameters are stored (similar to the Unix version) in configuration files (see also section 5). These configuration files will be updated during the installation and can be changed by a BSCW administrator on the [Options --> Admin]-page within the item “BSCW Server Settings” or by directly editing the respective configuration files (see below for further details). The standard set up should create an installation which should be appropriate in most cases. However, if you want to modify the default settings, you will find respective information in this section. Please note that, in general, in this section only Windows 2003/XP/2000/NT specific configuration options are explained:
BSCW server root definition
IIS configuration
Apache HTTP server configuration
BSCW registry settings
De-Installation
4.5.1
BSCW Server Root Definition
The “server root” - the hostname (and port) part of your BSCW servers URL - is specified in the BSCW server instance configuration file at /src/config.py. The variable SERVER_ROOT contains the absolute URL of your BSCW server and an optional port. If no port is specified the standard ports 80 (for HTTP) or 443 (for HTTPS) are assumed: SERVER_ROOT = 'http://bscw.domain.org/' SERVER_ROOT = 'http://bscw.domain.org:123/' SERVER_ROOT = 'https://bscw.domain.org/'
A fully qualified host name is required as server name “bscw.domain.org”, in order to allow the BSCW server to resolve its name to an IP address (SERVER_ROOT may not contain an IP address anymore!). Ideally you define a host name/nickname (A/CNAME) in your DNS zone, which points to your BSCW server host, e.g. server1.domain.org
A
1.2.3.4
server2.domain.org
A
1.2.3.5
bscw.domain.org
CNAME
server1.domain.org
Proceeding this way a future migration of your BSCW server from server1 to server2 will keep the well known URL http://bscw.domain.org/ and your license will not be invalidated by the migration.
4.5.2
IIS Configuration
The BSCW server requires additional virtual directory mappings of your Web server. They depend on the values specified for the RESOURCES_PREFIX and the SCRIPTS variables in the BSCW server 26
BSCW 4.2 Administration Manual
configuration. By default the virtual directory mappings are /bscw_resources
⇒
C:\BSCW\server\resources
/bscw
⇒
C:\BSCW\server\cgi
/pub
⇒
C:\BSCW\server\cgi
These directory mappings are set and configured automatically by the BSCW on Windows 2003/XP/2000/NT installation program. If you want to configure this directory manually, you have to perform the following steps: Add the new virtual directories to your default website. For the directory mapping bscw_resources you only need read access, but for the virtual directories bscw and pub you have additionally to allow execute access. In the properties dialog of virtual directory bscw and pub select the Directory Security tab. Edit Anonymous Access and Authentication Control. Only Allow Anonymous Access should be checked. In the Custom Errors tab the error code 401.5 must be set to default. For the virtual directories bscw and pub add the following application mapping: '.cgi' : "\python.exe" -u "%s"
BSCW uses its own built-in “Basic Authentication” scheme to check the access for the virtual directory /bscw. Therefore no authentication filter is necessary. These configuration will be done by the BSCW administration command > bsadmin conf_iis
4.5.3
Apache HTTP Server Configuration
For the Apache HTTP server (version 2.0 (resp. 1.3)), the setup process has automatically generated a configuration file \apache.conf, which contains all necessary configuration instructions. We recommend including the contents of this file into your Apache HTTP servers configuration file httpd.conf (into the main server or corresponding virtual server definition) with the directive: Include \apache.conf
Note: You must restart your Apache HTTP Server for the changes to take effect. Similar as in the IIS configuration, BSCW uses its own built-in “Basic Authentication” scheme check the access the server. To pass the authentication information through the Apache HTTP Server, you have to load, enable and configure the rewrite module. Alternatively you may also change the Apache configuration file httpd.conf manually to contain the following lines ( denotes the directory of your BSCW instance). LoadModule rewrite_module modules/mod_rewrite.so # BSCW aliases prefix -> directory Alias /pub
“\cgi”
Alias /bscw
“\cgi”
Alias /bscw_resources
“\resources”
# BSCW directory setting for authenticated users # configure rewrite module RewriteEngine on RewriteCond %{HTTP:authorization} (.*) RewriteRule .* - [E=HTTP_AUTHORIZATION:%1]
27
BSCW 4.2 Administration Manual AllowOverride None # Emable CGI scripts Options FollowSymLinks ExecCGI AddHandler cgi-script .cgi # Set index file DirectoryIndex index.html default.htm # Client access Order deny,allow Allow from all # BSCW directory setting for user anonymous AllowOverride None # Enable CGI scripts Options ExecCGI AddHandler cgi-script .cgi # Set index file DirectoryIndex index.html default.htm # Client access Order deny,allow Allow from all # BSCW directory setting for other resources (icons etc.) AllowOverride None # Client access Order deny,allow Allow from all
Note: The LoadModule directives (as given in apache.conf) do not work within a ... section. Please ensure to load the necessary additional modules (cgi_module, headers_module, rewrite_module) within the “Section 1: Global Environment” of the Apache HTTP server httpd.conf file. Apache HTTP Security Advisory: Over the last months several security problems have been discovered in the server source code and in third-party code that many websites rely on. Some of these problems are now being actively exploited on the Internet
If you are running an SSL-enabled Web server using OpenSSL, upgrade to at least version 0.9.6m or 0.9.7e of OpenSSL and recompile all applications that use OpenSSL.
Upgrade your Apache HTTP Server to version 2.0.52 (or 1.3.33) or higher.
4.5.4
BSCW Registry Settings
To simplify the process of upgrading, installing and de-installing the BSCW defines some settings in the registry at 28
These settings are read from the BSCW instance configuration file \src\config.py and are set automatically during the server start. Do not change them. The BSCW registry settings are used only if you upgrade or reinstall the BSCW server instance.
4.5.5
De-Installation
To ensure that the BSCW system is completely removed from your system during de-installation you should 1. Stop the IIS or the Apache HTTP Server. 2. Stop the BSCW server and all Python processes. 3. Start the BSCW de-installer program in the systems control panel. 4. If there are any files (e.g. *.pyc files) or directories left you can safely remove them manually. 5. If you do not want to keep any BSCW data you can remove the data directory as well. 6. Remove the virtual directories for the BSCW in your Web Server.
4.6
BSCW Services
This section contains instructions on how to configure the additional services provided for the BSCW shared workspace system. Configuration has to be done either in the BSCW instance configuration file (\src\config.py) or at operating system level (e.g. Windows Task Scheduler).
4.6.1
Configuration of the Microsoft Index Server
For the content search in your BSCW documents you can use either the Microsoft Index Server 2.0 (IIS4 - Windows NT 4.0, Option Pack) or the Microsoft Index Server 3.0 (IIS5 - Windows 2003/XP/2000). To use the Microsoft Index Server you have to append the package MSindex to your package list in your server configuration (i.e. append '../packages/MSindex' to your PACKAGES variable in the BSCW instance configuration file) and create a Microsoft Index Server catalog for the BSCW files directory. This can be done with the bsadmin command > bsadmin create_cat
Important: If you are using Microsoft Index Server 2.0 (IIS4 - Windows NT 4.0, Option Pack) you have to rescan new the catalog BSCW manually, i.e.
open the Index Server MMC, in the left pane of MMC, under the catalog BSCW double-click Directories,
in the right frame, right-click the BSCW files directory,
select Rescan,
in the Full Rescan dialog box, click Yes for a full rescan.
4.6.2
Folder Mail Delivery
BSCW version 4.2. does not support BSCW folder mail delivery on Windows. 29
BSCW 4.2 Administration Manual
5 Configuration of BSCW Servers The BSCW server can be configured by a set of configuration files which are stored in the instance source directory /src or, in the case of packages, in the directory where the source code for the packages is stored, e.g., in /packages/ldap/src
The standard configuration files in the instance source directory /src are: config.py General configuration of the BSCW server config_html_ui.py HTML user interface of the BSCW server config_icon.py Icons in the user interface of the BSCW server config_msg.py Configuration for Mime type related messages config_mime.py Mime type specifications config_convert.py Specification of archivers, encoders and converters config_meet.py Configuration of synchronous meeting facilities config_cal.py Configuration of the Calendar The above configuration files are described in this section. Please note the editing instructions within these files carefully when making any modifications. It should be noted that all configuration files are Python modules and on thus subject to Python’s programming language syntax.
5.1
config.py
This file defines the general server settings and server configuration of the BSCW server instance. Please note that all relative file and directory names are resolved using instance source directory /src
Below the names of the configuration variables, their meaning and their default settings are given. At least the variables mentioned in the “Section 1: MANDATORY server settings” the configuration file must be set since their default setting is not sufficient.
30
BSCW 4.2 Administration Manual
5.1.1
Section 1: MANDATORY server settings
SERVER_ROOT
The Web servers' root address. This should be an absolute URL specifying
the protocol (http or https)
the fully qualified domain name of the server
and optionally, the port number
See section 3.3.2 for further configuration hints of SERVER_ROOT. For example: SERVER_ROOT = 'http://bscw.domain.org' SERVER_ROOT = 'http://bscw.domain.org:8000'
Important Notes: You have to set SERVER_ROOT to before you apply for a BSCW license. A granted BSCW license (not the evaluation license) will become invalid if you change SERVER_ROOT or the standard SCRIPTS prefix (see below). In this case BSCW will complain with a “license error” message after the BSCW database server is restarted or the garbage collector has run. Hence, you need to apply for a new (royalty-free) “change server”license after changing the values of SERVER_ROOT or the standard SCRIPTS prefix. Of course, you might also reset SERVER_ROOT and SCRIPTS to the old values and restart (stop and start) the BSCW database server. SERVER_ADMIN
The mail address of the BSCW administrator. SERVER_ADMIN must be set to a valid and complete mail address.
List of BSCW users that have administrator rights, e.g.: SERVER_ADMINS = [ 'bscw-admin', 'diana', 'peter' ]
Note:The users listed here must be registered BSCW users and the names must match exactly. For domain restrictions see also SERVER_ADMINS_IP SERVER_ADMINS = []
SMTP_HOST
A hostname or an IP-address of a mail host that accepts mail posting by SMTP. Using the SMTP_HOST option is recommended, because it allows to set sender addresses correctly. If empty, the local mail delivery command as defined in SENDMAIL is used. (See also: local BSCW mail delivery (MDA_MTA))
SMTP_HOST = 'bscw.domain.org'
31
BSCW 4.2 Administration Manual
5.1.2
Section 2: Mail handling
SENDMAIL
A command line accepting mail (header+body) for posting via standard input. The patterns %(from)s and %(to)s in the SENDMAIL string are substituted by the sender and the recipients of the mail respectively (the recipients are separated by spaces).
Settings for the local BSCW mail delivery agent, which delivers mail directly into folders. Note: When local BSCW mail delivery is enabled, the BSCW server should only use the local mail server, therefore it is advisable to set SMTP_HOST = '' MDA_MTA specifies the local Mail Transfer Agent (MTA), currently
Setting MDA_MTA = '' or any unknown MTA will disable the BSCW mail delivery feature (this is the default). MDA_MBOX defines the local mailbox name for BSCW mda (this is
normally the BSCW user ID name) MDA_DOMAIN defines the domain name of the BSCW MDA (which is the
delivery domain of the local MTA for the local BSCW MDA mailbox) MDA_LOGLEVEL sets the BSCW mail deliver agent loglevel:
0
only fatal errors are logged
9
everything and even more is logged
MDA_LOGFILE specifies the BSCW mail deliver agent logfile MDA_HDRDESCR defines which headers are shown in the description of an uploaded email, e.g. MDA_HDRDESCR = ['From', 'To', 'Cc'] MDA_EXT = True (optional) appends the extension for the MIME type 'message/rfc822' (as defined in config_mime.py: .eml or .mht) to the email name. MDA_MTA = '' MDA_MBOX = 'bscw' MDA_DOMAIN = 'bscw.domain.org' MDA_LOGLEVEL = 3 MDA_LOGFILE = '../data/MdaLog MDA_HDRDESCR = []
32
BSCW 4.2 Administration Manual SEND_LIMIT
SEND_LIMIT is a tuple of (soft_limit, hard_limit). If an email
should be send by the send operation and the message becomes larger than the soft_limit, the user gets an hint that, he will send a large email. If the message is larger then the hard_limit, the sending of the message will be rejected. If one or both of the limits are 0, the test or both tests will be suppressed. SEND_LIMIT = (0, 0)
SEND_ADMIN
If set it specifies an email address which will be used as sender instead of the SERVER_ADMIN, when an user sends an email via the send operation.
SEND_ADMIN = ''
FAX_SERVER FAX_ATTACHMENTS
FAX_SERVER is the address of a fax server with a mail gateway (for
example the HylaFAX server, http://www.hylafax.org/). If it is not empty, BSCW offers an interface to send faxes with email with this server, i.e. the BSCW server sends either a text/plain or a multipart/mixed message with a fax to this server. To configure this message edit the template fax.mail in the BSCW messages directory. FAX_ATTACHMENTS contains a list of mime types for documents, that can be send in a multipart/mixed message to the fax server.
List (or tuple) of IP domain addresses. If not empty the remote address must match one of the given domains for a user in SERVER_ADMINS to become BSCW Administrator (see below). E.g. ('129.26.',) restricts admin access to the Fraunhofer Birlinghofen campus domain. Attention: This also restricts the user notification service (UNO)! If the SERVER_ADMINS_IP list is not empty, the IP address of the SERVER_ROOT resp. SERV_UNO_ROOT web server must be contained in this list, eg. SERVER_ADMINS_IP = [ '1.2.3.4',
# administrator IP address
'127.0.0.1',
# SERV_UNO_ROOT = 'http://localhost' or
'193.175.161.100',
# SERVER_ROOT = 'http://bscw.fit.fhg.de'
]
SERVER_ADMINS_IP = []
33
BSCW 4.2 Administration Manual MAY_REGISTER
List of BSCW users who have the right to register mail addresses - i.e. to invite new users to the system or to a workspace. This is in addition to SERVER_ADMINS who have this right anyway. There are two special cases: if MAY_REGISTER is [] Registration of new email addresses is allowed for all users. This allows all registered users to invite new users to the system. Also self-registration is possible. None Registration is allowed for all registered users, but self-
registration is forbidden. Note: Only MAY_REGISTER=[] allows self-registration by URL http://bscw.domain.org/pub/bscw.cgi?op=rmail
Do not reset this default until you have registered yourself on your BSCW System! MAY_REGISTER = []
REGISTER_DETAILS
A list of user details that must be filled in at registration time by new users. You may select a subset of the following user attributes: fullname (user’s full name), org (Organisation), phone (work phone). fax (Fax number), homephone (private phone number), mobile (mobile phone), post (postal address) - e.g. in order to inquire the user for his full name and phone number at registration you would configure: REGISTER_DETAILS = [ 'fullname','phone' ]
To allow registration without additional details, simply set REGISTER_DETAILS = None
Note: registration details will be stored with the email address until the registration process is finished – when searching for pending email addresses using the web-based admin interface you will see the registration details in the result listing. Once the registration process is finished, all details will be stored with the allocated user. REGISTER_DETAILS = None
RESTRICT_MAIL
A list (or tuple) of pairs (pattern, boolean) which restrict the set of email addresses that are accepted by BSCW for e.g. registration or invitation. If the list is not empty, then a new mail address is translated to lower case and matched against the patterns (see PYTHON module re). The boolean of the first matching pattern decides, if the mail address is accepted by BSCW. For example RESTRICT_MAIL = [('[^@]*@orbiteam.de', 1), ]
restricts accepted email addresses to the single domain orbiteam.de. Note: RESTRICT_MAIL does not apply, if the inviting user is in the list of SERVER_ADMINS. 34
BSCW 4.2 Administration Manual RESTRICT_MAIL = []
RESTRICT_SEND
A list (or tuple) of pairs (pattern, boolean) which restricts the set of users that are allowed to send email via BSCW. If the list is not empty, then the primary mail address of a user is translated to lower case and is matched against the patterns (see Python module re). The boolean of the first matching pattern decides, if a user may send email. For example RESTRICT_SEND = [('[^@]*@orbiteam.de', 1), ]
restricts users who may send email to all users who have registered with a primary email address in the domain orbiteam.de. RESTRICT_SEND = []
RESTRICT_FAX
If set, it specifies a list (or tuple) of pairs (pattern, boolean) which restrict the set of users that are allowed to send a fax via BSCW. If the list is not empty, then the primary mail address of a user is translated to lower case and is matched against the patterns (see Python module re). The boolean of the first matching pattern decides if a user may send email. For example RESTRICT_FAX = [('[^@]*@orbiteam.de', 1), ]
restricts users who may send fax to all users who have registered with a primary email address in the domain orbiteam.de. RESTRICT_FAX = ()
SCAN_FILE NO_VIRUSES_FOUND VIRUS_FOUND
Define a virus scanner which scans files during upload. The upload of files with a virus will be denied. SCANFILE specifies the command string to scan a file. Use the pattern '% (file)s' for the file name. Consider in the parameters of the scan
command to scan archive files (like zip) or emails. An empty value will deactivate the scanning. NO_VIRUS_FOUND gives a list of result codes which the scan command
will return if no virus is found. VIRUS_FOUND gives a list of result codes which the scan command will
return if a virus is found. Example for NAI McAffee VirusScan: SCANFILE = '/<path-to>/uvscan --mime --unzip %(file)s' NO_VIRUS_FOUND = [0,] VIRUS_FOUND = [13,] SCAN_FILE = '' NO_VIRUS_FOUND = [] VIRUS_FOUND = []
35
BSCW 4.2 Administration Manual
5.1.4
Section 4: web/proxy server settings
BSCW_REALM
HTTP Authentication parameter - as set in the Web server configuration. Note: If you are running different BSCW servers on one host then you must use a different realm for each server.
If not zero and the Host: header is sent by the client, then the BSCW server will use this header for generation of absolute server URLs. Otherwise the URL will be taken from the SERVER_ROOT or from the environment variable SERVER_NAME or from the socket.gethostname() method (in this order).
USE_HTTP_HOST = 1
GZIP_RESPONSE
Compress HTML pages if longer than GZIP_RESPONSE bytes and client supports 'gzip_resonse' (see bs_clientmap.py). GZIP_RESPONSE = 0
is no compression
GZIP_RESPONSE = 0
COOKIE_ AUTHENTICATION
Must be None when disabled or a triple (tagname, location, timeout)
when enabled. When enabled, the BSCW server does user authentication via HTTP cookies. This overrides the user authentication (perhaps already) done by the HTTP server. In order to avoid confusion, the HTTP server should not be configured to do authentication when COOKIE_AUTHENTICATION is enabled. If the MS Internet Information Server (IIS) is used please see: http://support.microsoft.com/support/kb/articles/Q176/1/13.ASP timeout = None do not verify authentication tag (low security!) timeout = 0 authentication tag does not expire timeout = n authentication tag expires after n minutes location = None use op_login for BSCW authentication location = URL jump to URL for authentication e.g. COOKIE_AUTHENTICATION = ('bscw_auth', None, 120) COOKIE_AUTHENTICATION = None
POST_ AUTHENTICATION
When enabled (POST_AUTHENTICATION = 1), all POST requests must be authenticated by a hidden variable. This is not well tested yet. Some rarely used BSCW forms might respond with “Error: Old token”. Hence it is disabled for now. 36
If not empty then all users that are removed from the system are logged in the file LOG_REMOVED_USERS. An entry is a line of the form: user_name:user_id[:?]mail_address
An email address preceeded by '?' denotes a mailaddress that was not owned by the user at the time of removal (hence the user has not received an email notification). LOG_REMOVED_USERS = '../data/removed_users'
PASSWD PASUPD PASLOG
PASSWD - Web server password file PASUPD - Web server password database update program PASLOG - Web server password database update logfile (only used if PASUPD is set)
If PASSWD is not empty the password file PASSWD is automatically managed by BSCW. Note:
If you change the PASSWD file, you must also point your HTTP server to the new file (e.g. run bsadmin conf_apache and restart httpd with the new configuration).
Some HTTP servers need a password database. In this case PASSUPD must be set to a password update program.
See the sections for the Web server configuration for details (3.3.1 (Unix), 4.5.2 or 4.5.3 (Windows). PASSWD = '../data/htpasswd' PASUPD = '' PASLOG = '../data/PASUPD_log'
Define the CGI scripts that may be called the HTTP server. Given the URL http://bscw.domain.org/testing/bscw/bscw.cgi/0/25, the HTTP server will split this URL into the SCRIPT_NAME "/testing/bscw/bscw.cgi" and the PATH_INFO "/0/25" The BSCW server splits the script name further into the prefix "/testing/bscw/" and the script "bscw.cgi" Note: the prefix always starts and ends with a '/' and the “no Javascript indicator” 'nj_' is always stripped from the beginning of script. The BSCW accepts a SCRIPT_NAME, if the prefix is found in the SCRIPTS dictionary: prefix->(username,directory,create_scripts,extra_scripts)
and the script is found in one of the two lists create_scripts or extra_scripts. If username is None, the user must authenticate. Otherwise the BSCW server assumes that the client may use the script without authentication (e.g. for anonymous access or access controlled by the client's host domain). In the latter case the user will get access according to username. Note: The usernames must be different in all tuples (username, ...) and there must exist at least a tuple with username None and a tuple with username “anonymous”. The command “bsadmin chkconfig” needs the dictionary entry (which might be the same for all prefixes) in order to automatically create the scripts listed in create_scripts. For special purposes you might also create your own CGI scripts that eventually call the BSCW service. These scripts must be listed in extra_scripts. Note: The nj_* scripts that are used for non-Javascript access are also created automatically by “bsadmin chkconfig“they should not occur in create_scripts or in extra_scripts. Note: If username is not equal to None (and if necessary), the command “bsadmin chkconfig“ will also copy the scripts in the extra_script list if they occur in the SECURE_SCRIPTS list. The script is copied from the dictionary in tuple with username equal to None, so it must exist in that directory. Note: The extra_script and SECURE_SCRIPTS feature is intended for experts only. Note: CREATE_SCRIPTS is not used elsewhere. It is only defined for convenience.
URL prefix for icons, styles etc. If it starts with '/' it is absolute (on the server), if not the prefix is taken relative to the users' SCRIPT prefix (see above). Note: the prefix must end with '/' Note: whenever RESOURCES_PREFIX is altered the Web servers configuration and the BSCW index page has to be updated with the commands: bsadmin conf_apache bsamdin conf_iis bsadmin index_page
(Unix) (Windows) (Unix/Windows)
See the sections for the Web server configuration for details (3.3.1). RESOURCES_PREFIX = '/bscw_resources/' PATH_INFO_SLASH
Must have the values '' or '%2f' or '%2F'. This should only be set not empty if the Apache 2 server is used and "AllowEncodedSlashes On" is set. It must be equal to the encoding that Apache 2 uses for URI path segments (should be '%2f'). Warning: This is an experimental feature. Many DAV clients do not work with encoded slashes in URI path segments. Better leave it empty by now.
PATH_INFO_SLASH = ''
HTTP_PROXY FTP_PROXY GOPHER_PROXY
Specify proxies for various server types (i.e. http, ftp, gopher) by defining a variable named _PROXY. This variable denotes the proxy server for this type by the form ':<port>'. For example HTTP_PROXY
= 'proxy.orbiteam.de:3128'
FTP_PROXY
= 'proxy.orbiteam.de:3128'
GOPHER_PROXY = 'proxy.orbiteam.de:3128'
The proxies are used by the BSCW server if it fetches or verifies an URL or if it connects to a web search engine within a www search. HTTP_PROXY = '' FTP_PROXY = '' GOPHER_PROXY = ''
BYPASS_PROXY
Gives a list for domains, where the proxy should be bypassed, i. e., a host whose end of its name matches one of the domains, will be connected directly. Normally it should be set to the local domain. For example BYPASS_PROXY = ['fit.fraunhofer.de', 'orbiteam.de' ]
39
BSCW 4.2 Administration Manual BYPASS_PROXY = []
FTP_GATEWAY
Sets a FTP firewall gateway for the export operation.
FTP_GATEWAY = ''
WEBDAV_APPS WEBDAV_APP_MODE
Controlls the get and edit actions for documents, that can be opened by applications via WebDAV. For example with MS Office XP or MS Office 2003 one can save documents back to the BSCW server. Prerequisites: WebDAV enabled, no COOKIE_AUTHENTICATION, Browser with ActiveX, MS Office XP or 2003, the document name must have the right extension WEBDAV_APPS defines a list of MIME types for documents which can be
opened by an application via WebDAV. WEBDAV_APP_MODE 0 - disable this feature. 1 - action 'get' with old behavior, action 'edit' calls the application
with a WebDAV link. 2 - action 'get' calls the application with a WebDAV link, no action 'edit'. 3 - action 'get' calls the application with a WebDAV link (in view mode for MS Office 2003), action 'edit' (in edit mode). WEBDAV_APPS = [ 'application/vnd.ms-access', 'application/vnd.ms-excel', 'application/vnd.ms-project', 'application/vnd.ms-powerpoint', 'application/msword', 'application/rtf', ] WEBDAV_APP_MODE = 0
5.1.5
Section 5: BSCW appearance settings
USER_SEARCH_LIMIT
Maximum number of matching hits by a User Search.
USER_SEARCH_LIMIT = 100
MEMBER_SEARCH
Defines, if the search for BSCW users, is allowed on the add member form.
MEMBER_SEARCH= 1
40
BSCW 4.2 Administration Manual SCROLL_LIMIT
Many browsers crash, when they should display long container listings. To prevent users from requesting such precarious pages, the number of entries in a listing can be limited. If set to 0, there is no restriction to the number of entries.
SCROLL_LIMIT = 500
HELPER EDITOR
Mime type for BSCW uploading and edit helper. On client side, this Mime type should be configured to one of our BSCW uploader and generic editor programs.
STYLE_SCALES defines a list of subdirectories of the directory STYLES_DIR, in which changes to the default style sheets and changes in config_styles.py for different font sizes can be located. STYLE_COLORS defines a list of subdirectories of the directory STYLES_DIR, in which changes to the default style sheets and changes in config_styles.py for different color schemes can be located. STYLE_CLIENTS defines a list of tuple pairs, containing an user agent pattern and a subdirectory in the STYLE_SCALES directories. If the environment string HTTP_USER_AGENT matches the pattern, then changes to the scaled style sheets and changes in config_styles.py for this user
agent can be located in the corresponding directory. STYLE_SCALES
REFTYPES is a list of MIME Types of documents that may contain URLs with relative anchors, especially '../'-references. If a web browser resolves such '../'-references it removes elements at the end of the documents URL path. Hence a sufficient number of (dummy DOTDIR)
directories must be inserted into the document's URL. Note: DOTDIR must contain exactly one '/' and it must be the last character. REFTYPES = [ 'text/html' ] DOTDIR = '*/'
ARTICLE_TYPES
The set of types a Discussion and Note object can have. The configuration files bs_iconconfig.py and lg_msgconfig.py (in the language directories) must have corresponding entries.
specifies a name pattern and works like the 'index.html' feature in most HTTP-Servers: if a Folder contains an object matching the the given pattern ('*' matches '-' or '') then the object is presented to the anonymous user instead of the folder listing. E.g. if INDEX_PAGE_EXT='index*.html' and an anonymous user has selected the german language (de) in his browser, then the Folder contents are looked up for the names 'index-de.html' and 'index.html' (in this sequence). For compatibility with old BSCW installations, if INDEX_PAGE_EXT starts with '.' (a file extension .<ext> is specified) it will match the names index-.<ext>, index.<ext>, and english.<ext>.
INDEX_PAGE_EXT = ''
LOCAL_URL_PREFIX
It is possible (for administrators only) to make URL links into the local file system. If LOCAL_URL_PREFIX is not empty and the URL has the form LOCAL_URL_PREFIX: then the file or directory on the local filesystem is accessed by the GET operation on the URL (a relative local file path is interpreted relative to the src directory). If the directory contains a file named index.html (recommended!) the contents of index.html are returned instead of a directory listing. Note: This feature is experimental and has obvious security implications! It is disabled by default.
LOCAL_URL_PREFIX = ''
SYS_MSG
Display system messages when logging into BSCW. If SYS_MSG > 0, you must have files sys_msg1.html, sys_msg2.html ... sys_msg<SYS_MSG>.html
in the default language directory (you may also have language dependent versions of these files. See messages/en/sys_msg1.html as an example). The files are displayed to users as system messages and must be confirmed. 42
BSCW 4.2 Administration Manual SYS_MSG = 0
Set, if the server is unavailable for processing requests. The message in file messages/en/<SYS_BUSY>.html will be returned. (See /messages/en/sys_busy.html as an example)
SYS_BUSY
SYS_BUSY = ''
Locations of various resources for the URLs in the BSCW Banner.
SERVER_HOME SERVER_HELP SERVER_INFO
SERVER_HOME - BSCW server home page
SERVER_HELP - BSCW Help files
SERVER_INFO - BSCW server info page - by default it shows the index page in the scripts directory for anonymous (see SCRIPTS).
Note: If you install help pages in further languages, e.g., in esperanto, you have to add a new variable SERVER_HELP_ESPERANTO. SERVER_HOME SERVER_HELP SERVER_HELP_DE SERVER_INFO
Should be set to the timezone that corresponds to time.localtime and should be given in the form “Continent/City”. If you are not sure, use the special value “localtime”.
SERVER_TIMEZONE = 'localtime'
BSCW_LICENSE
URL used for requesting BSCW license upgrades. This should not be changed (unless you obtain licenses from another party).
Using the user notification services a BSCW user does not need to contact its BSCW server(s) so often to check for new events. If the user notification services are activated, the users' event preference page provides a column for subscription of the “Daily Report”, the “Direct Email” notification or the “Monitor Applet” (depending on the UNO service configuration). By default no report is sent to new users, so each user may decide to subscribe to the workspace report by himself. The server administrator can change this behavior using the AUTOSUBSCRIBE_REPORT flag. If this is enabled new users will automatically subscribed to the user notification service. (Each user may then un-subscribe from the service.) To activate the user notification service the BSCW administrator has to start an additional UNO server (bs_servuno). See section “SERVERS” for details on how to start bs_servuno. Note: to not interfere with the user notification service the workspace activity report configuration of versions prior to BSCW 4.2 must be disbabled by removing the crontab (Unix) or the task scheduler (Windows) entry for bsadmin notify -a. Also, the following variables have to be set for configuration of bs_servuno: SERV_UNO_ROOT: Defaults to SERVER_ROOT. However when SSL is
used then another non-SSL (i.e.) HTTP access to the local BSCW server must be given here. 'http://localhost' might be a good choice in this case. SERV_UNO_STATE: A file name for saving the state of the bs_servuno service must be given here. The file is written, when the bs_servuno
is stopped and read when the server is started again. Attention: If the SERVER_ADMINS_IP list is not empty, the IP address of the SERVER_ROOT resp. SERV_UNO_ROOT web server must be contained in the SERVER_ADMINS_IP list, eg. SERVER_ADMINS_IP = [ '1.2.3.4',
# administrator IP address
'127.0.0.1',
# SERV_UNO_ROOT = 'http://localhost' or
'193.175.161.100',
# SERVER_ROOT = 'http://bscw.fit.fhg.de'
]
45
BSCW 4.2 Administration Manual SERV_UNO_TIMES: A dictionary containing fine tuning parameters for bs_servuno; if is set to SERV_UNO_TIMES = None the default settings
are used (as shown below). To overwrite the default settings for fine tuning parameters use e.g.: SERV_UNO_TIMES = { 'TdelayDirect': 10., 'MaxRetry': 20, }
The defaults are: 'TdelayDirect': 60: Delay direct notification one minute for the first affected user. This is to accumulate more events in the direct notification mail. 'TdelayNextProc': 3: Add a delay of 3 seconds for the next
affected user. This is to avoid an overload of the mailserver if a lot of users are affected, 'TdelayNextDirect': 120: Delay the next direct notification for
the same user two minutes. This is to avoid an overload of the user. 'TdelayDayly': 3: Add a delay of three seconds between daily
notification mails. This is to avoid an overload of the mailserver if the service has to send the notification to a lot of users. 'TdelayRetry':
300: Add a delay of 5 minutes after the
notification has failed and retry then. 'MaxRetry': 11: 11 retries that are delayed with TdelayRetry. 1200: After MaxRetry the notification is delayed 20 minutes (0 may be assigned here, then there will be no retry upto next midnight). 'TdelayFailed':
'FailMessagesAt': 10: Log an error message every 10th failure
(first, 11th, 21st ...) Note: No error messages are logged after MaxRetry (special values 1: each message 0: never) 'MaxJobs': 20: Maximum number of parallel running mail processes. Note: On Windows it might become necessary to reduce overall the system load by setting 'MaxJobs' to a smaller value, e.g. 10. 'QueueInfo': 20: Show job queue status after 20 jobs are queued (use values: 2n * MaxJobs)
Report number of queued jobs if more than QueueInfo jobs are queued. 'ReportTime': '00:00': Start daily report at 00:00 (must be
before 07:00) WSREPORT: = 1 (= 0) enable (disable) the daily report. WSREPORT_DIRECT: = 1 (= 0) enable (disable) the direct email report.
Note: When bs_servuno does not run the daily report and the direct email report are disabled. Whenever the values of WSREPORT or 46
WSREPORT_DIRECT are altered bs_servuno must be restarted to take
these changes into effect. AUTOSUBSCRIBE_REPORT: defines the default subscription for all users
(note that once a user has changed its subscription preferences this flag will have no further effect - but the administrator may use the 'bsadmin report' command to change a user's report subscription later) REPORTLOG: points to a file in which a protocol about the reports is logged. For example: REPORTLOG = '../data/report.log'
BSCW Awareness Service configuration Setting ALWAYS_CREATE_READEVENTS > 0 enables the creation of read events, even if a user has already read the document and the document was not modified in between. This is sometimes needed for enhanced awareness. Setting ALWAYS_CREATE_READEVENTS < 0 supresses generation of read events.
ALWAYS_CREATE_READEVENT = 0
AW_MONITOR_ENABLED
Monitor Applet configuration Setting AW_MONITOR_ENABLED to 1 enables the Monitor Applet, which provides awareness of online users and recent events. The Applet will be accessible on the home folder of each user. Note: The Monitor Applet requires the BSCW XMLRPC-API. Setting AW_MONITOR_ENABLED to 1 mandatory requires to enable the BSCW XMLRPC-API by setting ACCEPT_XML_RPC to 1 (see below)
The SERVERS list is used for starting (and stopping) BSCW servers. The triple (GSERV, DBMOD, GSMOD) naming the BSCW database server is automatically inserted by bs_config.py. Only extra server addresses and implementation modules should be specified here. The first element specifies the address, the second is the service module and the third is the RPC protocol module (optional, default is GSMOD). The following RPC protocol modules are available: AF_UNIX address family (Unix sockets) 'cl_servublk' 'cl_servinet' AF_INET address family (TCP/IP) 'cl_servinet_ext' AF_INET address family (non Python service)
Note: an address of the AF_INET address family is specified as (host, port) whereas an address for AF_UNIX is a file name. Example for starting the user notification server: 1) On Unix using Unix domain sockets (AF_UNIX; preferred on Unix): SERVERS = [ ('../data/ServUno', 'bs_servuno', 'cl_servublk'), ]
2) On Windows/Unix using TCP/IP sockets (AF_INET): SERVERS = [ (('localhost', 12866), 'bs_servuno', 'cl_servinet'), ] SERVERS = []
DBS_LOGFILE DBS_LOGLEVEL
Database Scheduler The (optional) database scheduler distributes BSCW events to registered XML-RPC services. In order to become notified about subscribed events an external XML-RPC service has first to register at the database scheduler and define its XML-RPC URI (where the service implements its own serv_notify() procedure). After successful registration the external XML-RPC service receives a handle (the serv_id) which has to be specified in all subsequent calls to the event scheduler. Beside XML-RPC service registration, event type subscription and event notification, the event scheduler allows registered external XML-RPC services to submit events with the method es_enter(). The database scheduler is controlled via the 'bsadmin dbsched' commandline script. DBS_LOGFILE: Specifies the database scheduler logfile DBS_LOGLEVEL: Database scheduler loglevel: 0 9
only fatal errors are logged everything and even more is logged
DBS_LOGFILE = '../data/DBS_Log' DBS_LOGLEVEL = 3
48
BSCW 4.2 Administration Manual
5.1.7
Section 7: BSCW database server settings
Simulates “soft links” in the BSCW file store on Windows 2003/XP/2000/NT. A list (or tuple) of pairs (path-pattern, substitute) determines the actual location of a BSCW file. E.g. if
FILES_SWITCH
FILES == 'D:\\files'
(see below), then FILES_SWITCH = (('D:\\files\\01', 'E:\\files\\01'))
will substitute all BSCW file paths starting with D:\\files\\01 by file paths starting with E:\\files\\01. This may be used for distributing the BSCW file store on different disks etc. Note: Some bsadmin tools like bsadmin fsck do not support this feature and may give wrong results. FILES_SWITCH = () REOURCES_DIR LANGUAGE_DIR
Directories with the location of the CGI scripts, the BSCW resources and the message files. (relative paths are interpreted relative to /src) - BSCW resources - BSCW language templates
BSCW Storage: FILES - Root directory of document file tree TEMP - Directory for temporary files TABLES - BSCW database tables (fast restart) STORE - BSCW storage file CLEAN - BSCW garbage collect & scratch file SAVE - BSCW garbage collected backup file
FILES TEMP TABLES STORE CLEAN SAVE
The files STORE (BSCW database file) and CLEAN (scratch file for garbage collection) must be files (or soft links) on the same file system. When finished, the garbage collector will simply switch these files by renaming, i.e. it does: rename(STORE, STORE+'X') rename(CLEAN, STORE) rename(STORE+'X', CLEAN)
We recommend the directories TEMP and FILES being on the same file system. In this case, only a link (instead of a copy) is done to put a temporary file in the right place, e.g. document upload. FILES TEMP TABLES STORE CLEAN SAVE
All requests to BSCW are logged in this file. Should be set for analysing purposes only. A log entry contains the following information (divided by blanks):
Use a pair of storage files: one is active, the other is used for garbage collecting. Might be useful on Windows where the garbage collector cannot switch reliably between GARBAGE and STORE or when block devices should be used as BSCW data storage. To enable STORE_PAIR:
Stop the database server.
Define two storage files or devicees (filenames STORE and CLEAN). For example: STORE_PAIR = ('../data/StoreA', '../data/StoreB')
or STORE_PAIR = ('/dev/dsk/c4t2d0s6','/dev/dsk/c4t2d0s7')
Start the database server.
If all is working well, the CLEAN file can be removed. This file is not needed anymore. However, do not remove the STORE file, which now contains a pointer to one of the files in STORE_PAIR. The garbage collector will now switch between the two files in STORE_PAIR.
Note: The filename in CLEAN is still used as a prefix for key and offset table files needed by the garbage collector. Note: “bsadmin getconfig STORE” shows the actually used file from STORE_PAIR.
GSMOD - Server connection module GSERV - Address of Database server socket GSMOD_CAN_FLUSH - flush() does work on "socket" file objects
Instead of cl_servunix the modules cl_servublk and cl_servinet may also be used for local database server connections (e.g. if neither flush() nor seek() works on file objects refering to Unix domain sockets, or if Unix domain sockets don't work at all). In the latter case, tuples like ('localhost', 12966) consisting of a hostname and port number must be used for GSERV and AWSERV. #(Default on Unix) GSMOD GSERV GSMOD_CAN_FLUSH
= 'cl_servunix' = '../data/Socket' = 1
#(Default on Windows 2003/XP/2000/NT) GSMOD GSERV GSMOD_CAN_FLUSH
ACCEPT_XML_RPC
= 'cl_servinet' = ('localhost', 12966) = 0
BSCW offers an XML-RPC API to most of its actions listed in cl_action.py. Access via XML-RPC calls must be authenticated using basic authentication and all methods are subject to access rights control very much the same as the "normal" HTML user interface. Use the ACCEPT_XML_RPC variable to allow or prohibit access to the BSCW server via the XML-RPC protocol (HTTP POST, Content-Type: text/xml). If ACCEPT_XML_RPC == 0, XML-RPC requests will be rejected by BSCW with the HTTP error code 501: content_unsupported. For documentation on the XML-RPC API see section “6.4 X-BSCW API”.
ACCEPT_XML_RPC
5.2
= 0
config_html_ui.py
The user interface configuration file determines what actions will appear at the user interface. All actions will subsequently be filtered for access control and feasibility at run time. This configuration file allows a BSCW system administrator to define so-called user profiles. A user profile defines those actions which a user who has selected the respective profile sees in the BSCW interface. User profiles may be defined according to the expertise of particular user groups (e.g., beginners, advanced users or experts) or according to other classification schemes that may be appropriate for a particular BSCW server installation. The default configuration file config_html_ui.py as delivered with the BSCW server software comes with three pre-defined profiles called BEGINNER, ADVANCED and EXPERT (see below). These profiles are upward compatible, i.e., the BEGINNER profile is a subset of the ADVANCED profile which in turn is a subset of the EXPERT profile. These profiles should only be considered examples: A BSCW administrator may modify the actions, buttons, etc., which shall appear in the interface of 51
BSCW 4.2 Administration Manual
the respective profile to the requirements of his or her specific user community. The profiles below apply unless the end user explicitly selects an action to appear at the user interface (action [ Options --> Preferences ]). Profiles should have values 2**n to facilitate mask evaluations (see below). By default, the following bit masks for user profiles are provided: ui_no
=
0
# action will not appear for any user
ui_beginner
=
1
# action will appear, if user has chosen beginner level
ui_advanced
=
2
# advanced level
ui_expert
=
4
# expert level
ui_java
=
32
# action will appear in java interface
ui_waste
= 128
# action will be allowed in the waste
ui_yes
= 255
# action will always appear at ui
The variable ui_profiles defines the list of available u/i profiles that the user may choose from. The second value is used to translate the profile’s name and must correspond to a variable in /messages/en/lg_msgconfig.py. ui_profiles = [ (ui_beginner,
'ui_beginner'),
(ui_advanced,
'ui_advanced'),
(ui_expert,
'ui_expert'),
]
The default profile for new users (when registering) is defined as follows: default_profile_new = ui_beginner
The default profile for existing users (this applies when upgrading from versions lower than 3.3 of the BSCW server) is defined as follows: default_profile = ui_expert
In the lists below, actions in the user interface may be set to one of the predefined action profiles, e.g. to ADVANCED. This value will be filtered by the user's individual user interface profile, e.g., ui_beginner. Action profiles may be combined to allow for more flexibility, e.g., an action profile == ui_advanced | ui_expert means that both users with profile ui_advanced and users with profile ui_expert will have this action at their interface. Other combinations are possible. BEGINNER = ui_beginner | ui_advanced | ui_expert
# ascending profiles
ADVANCED = ui_advanced | ui_expert
# ascending profiles
EXPERT
= ui_expert
ADMIN
= ui_yes & ~ui_java
What follows in the config file is the list user_acts which specify the actions in the user interface according the profiles. The list MultiActions specify the actions which can be used on a selection of BSCW objects.
5.3
lg_msgconfig.py
The lg_msgconfig.py files specifies numerous text strings which are used in the interface of the
52
BSCW 4.2 Administration Manual
BSCW server. Since these text strings are obviously language dependent, they are stored in the respective language directories, i.e., there exists a file lg_msgconfig.py in /messages/en as well as in /messages/de and possibly in other language directories. The file consists of a set of entries where each entry has the form InternalName
= 'Interface text string'
where InternalName is the name of an entity in the BSCW server source code and Interface text string is the external representation of the entity in the user interface. Obviously, InternalName is the same character string for all languages whereas Interface text string is, in general, specific for each language. For example, the lg_msgconfig.py file for English contains the following two lines Folder
= 'Folder'
ChangeEvent
= 'changed'
whereas the lg_msgconfig.py file for German contains Folder
= 'Ordner'
ChangeEvent
= 'geändert'
Note that the internal name and its external representation may be the same as for “Folder” (usually only in English) or it may be different as for “ChangeEvent” and “changed” (and, in general, for other languages than English). A BSCW system administrator may modify the user interface of his or her BSCW server by replacing interface text strings, e.g., if the ChangeEvent entry is modified to ChangeEvent
= 'modified'
the change event would appear with the name “modified” in the user interface. Whereas InternalName must always be one word conforming to Python naming conventions, Interface text string may consists of several words and may include HTML mark-up and also parameters for variable parts and must therefore be enclosed in quotes (single ', double “ or triple “““). For example: ChAccessEvent
= 'access rights changed'
no_objects
= '
<STRONG>No objects, currently.
'
CreateEventMsg
= 'created by %(name)s, %(date)s'
The entries are not listed in detail here. The lg_msgconfig.py files for English is the “default” file, i.e., if a lg_msgconfig.py file for a language different from English is lacking a translation, the entry is taken from the English file. Therefore, you should not remove any entries from the file /messages/en/lg_msgconfig.py. lg_msgconfig.py files for different languages, the order of the entries in the files should not be modified, nor should entries be removed completely. Entries which should not or cannot be translated, should be commented out for performance reasons. Commenting out entries from a lg_msgconfig.py files for languages other than English may be sensible, e.g., if a translation is not desired which is normally the case for system messages.
5.4
config_icon.py
This is (an excerpt from) the configuration file for configurable icons. For further description see 53
This is (an excerpt from) the configuration file for document types or so-called user friendly mime types (see following section 5.6 for more information on MIME-types). access
= 'MS Access'
aiff
= 'AIFF'
amipro
= 'AmiPro'
... zip
5.6
= 'Zip/Winzip'
config_mime.py
This is the configuration file for the MIME-types. Default MIME-type information for BSCW details can be extended or modified directly for system-wide effect. To add MIME-types, add an entry to the list below. Also consider adding an entry to bs_iconconfig.py if the type should have its own icon (otherwise the 'Unknown' icon will be used) and adding an entry to config_msg.py for the description of the MIME-type. The format for entries is: name = (MIME-Type, suffix)
where
name is the name of type's icon (in config_icon.py) and description (in config_msg.py).
The name must be unique and conform to Python naming conventions; MIME-Type consists of a type and a subtype divided by a slash (use lower case letters); suffix is used by document conversion assistant and to determine the document type by extracting a file archive (<= 3 characters recommended). Note: Only a subset of the IANA (and common, non-standard) media-types are specified here. For more information on MIME-types see:
This file configures the tools available for the conversion assistant. The system commands for archiver, encoder or converter tools are given in the following three lists respectively. The Archivers list contains triples (type, create, extract) with type
the mime-type for the archiving tool
create
the shell command to create an archive
extract
the shell command to extract files from an archive
The shell commands have to be specified with an absolute pathname and are normally executed in a temporary directory in BSCW Temp. In a shell command the following patterns can be used: %(src)s the absolute path of the source file %(dest)s the base name of destination file
In squared bracket some additional parameters can be set: [S_EXT=.xxx]
specifies the extension of the source file
[D_EXT=.xxx]
specifies the extension of the destination file
[D_NAME=%(dest)s.xxx]
or
[D_NAME=%(src)s.xxx]
specifies the name of the destination file
[E_DIR=xxx]
specifies a directory, where the tool should be executed 56
BSCW 4.2 Administration Manual
Multiple parameters can be separated in the squared bracket with a semicolon.
5.8
config_meet.py
This is the configuration file for CU-SeeMe reflectors, the synchronous collaboration tools and the online directories. The file contains the counter ID for a unique number and three lists CuSeemeServer, Applications and OnlineDirs. A CU-SeeMe reflector consists of a 3-tuple (, , ), where is the name of the CU-SeeMe reflector, a unique number and the IP name or IP address of the reflector. Examples: CuSeemeServer.append('BSCW Conference Server', 2, 'ora.fit.fraunhofer.de') CuSeemeServer.append('CSCW Demo-Center', 3, 'chili.fit.fraunhofer.de')
A synchronous collaboration tool consists of a 3-tuple (, , <params>), where is the name of the tool, a unique number and <params> a 2-tuple (<mime_type>, ). Here <mime_type> gives the Mime Type to start the application and is a command string to call a user. In the command string following substitutes can be used: %(host)s IP address for the host of the participant, %(name)s the name of the participant, %(email)s the Email address of the participant. Examples: Applications.append('Microsoft Netmeeting', 22, ('text/iuls', """< [res] hr=0 ip=%(host)s port=1720 mt=text/iuls >""") ) Applications.append('Netscape Conference', 27, ('application/x-conference', """[Call] Direct=%(host)s EmailAddr=%(email)s Name=%(name)s""") )
(Deprecated) An online directory consists of a 5-tuple (, , , , ). is the name of the directory service. and the are URLs with a link to the directory. has to be directly connectable with an email address, i.e., it usually has to end with a '/'. gives a reference a icon in config_icon.py. is a unique number. Examples: OnlineDirs = [ ('BigFoot', 'http://www.bigfoot.com/',
This is the configuration file for the calendar. Please note that not all entries are meant to be configured by the administrator here. Especially the settings of flags, categories and appoint_status should not be changed. BSCW administrators may change the default preferences for each user’s calendar here – the calendar_flags contains the sum of all enabled calendar flags (cf. list of flags). The file also contains defaults for the display of appointments in different views. For each view (y = year, m = month, w = week, d = day) a list of potential (’allowed_x’) and displayed (’view_x’) style
items is specified.
58
BSCW 4.2 Administration Manual
6 Administration of BSCW Servers There are three methods to administer the BSCW server:
through a HTML interface available to those users who have been registered as server administrators in the variable SERVER_ADMINS of the BSCW server instance configuration file /src/config.py (see section 5.1),
by direct editing the configuration files described in section 5 with a text editor of your choice,
through the bsadmin scripts which are available in the instance directory of the BSCW server (the bsadmin script may only be invoked by the user who installed the BSCW instance, e.g. the BSCW adminstrator user ID).
It may depend on the particular task which methods can or has to be used. For instance, the initial set-up of the BSCW server requires editing the BSCW instance configuration file /src/config.py with a text editor. If the server is running, further modifications of the configuration file may either be done by direct editing or through the HTML interface. Administrational tasks such as removing or adding users require a running server and can only be done through the HTML interface or with the bsadmin scripts. Starting or stopping the server can only be done with the bsadmin script. In general, it is recommended to use the HTML interface after the BSCW server has been installed successfully and started with the bsadmin script since it provides all the functionality which is needed for a system administrator. Please note that a server administrator needs to understand what s/he is doing. Any actions carried out by the server administrator may destroy data or may even damage the BSCW server instance in a way it does not run anymore. As a server administrator you are also responsible for other measures against loss of data. It is urgently recommended to install a regular back-up procedure for the data of the BSCW server, e.g., to recover in case of hardware or software crashes. In particular, it is highly recommended to make a back-up of the system, including the configuration files, if you want to make modifications to the system through the administrator tools described in the following sections.
6.1
Administration through the HTML Interfaces
A running server can be administered through the HTML interface. (Note that most administration tasks do not need to shut down the server; some even require a running server.) If you are registered as a BSCW administrator in the variable SERVER_ADMINS of the BSCW instance configuration file /src/config.py, you will find the action [Admin] in the [Options] menu. This is the start page from which all administrational operations can be carried out. If you click on Start garbage collection, the garbage collector is started. This is, for instance, necessary if you have installed a new license. The sections BSCW Server Configuration, Reflector Administration, Synchronous Collaboration Tools, Interface to Online Directory Service and Conversion and Archiving Tools are related to the configuration files described in section 5 Configuration of the BSCW Server. Clicking on one of the entries in these sections will present you with a form through which one of the configuration files can be modified.
59
BSCW 4.2 Administration Manual
For instance, clicking on BSCW Server Settings will show the following form:
This is a form showing the current version of the BSCW instance configuration file /src/config.py. It can be edited, e.g., you may change the email address of the server administrator, and the changed form may then be used to replace the current version. Clicking on Archivers will show the following form:
60
BSCW 4.2 Administration Manual
In this case, the form includes entries to make extensions to the configuration file config_convert.py, in particular to add new archiving tools to the BSCW server (see section 5.7) in a more structured way. The section BSCW Access Management is related to management of existing and new users of the BSCW server. Clicking on User Administration shows the following form to search for registered users of the system:
After specifying a query and submitting it, the system will present a list of one or more users (in case the query matched registered users). Note that the search can be restricted to particular types of email addresses, e.g., those which are allocated, pending or bounced. The result of a query may look as follows:
Below the names of the users, several actions are provided which the system administrator may apply to the respective users, for example, remove the user from the system, rename the user, edit properties of the user such as language preferences, password or access rights on the server. Clicking on New Mail Address shows the following form, which is used to add new email addresses to the system. Note that this is usually the first step to register new users in case that selfregistration of users is disabled (see section 6.3).
After entering an email address and clicking on “OK” the following user info page is shown:
61
BSCW 4.2 Administration Manual
The administrator may then continue with the registration process for the user, i.e., select a user name and password. The administrator may allocate the email address to an already registered user, or set the email address to “bounced” status (see section 6.3). Please not that the system does not send any message to the user, i.e., the administrator should then contact the respective user to communicate the name and password of the registered user. The management of BSCW licenses is handled through the section BSCW License Management. Clicking on Upgrade License shows the following form:
The get license (request status) button is used either to get information about the license that is currently requested or it is used to install a new license after it has been granted. The new license button is used to submit a request for a new license, e.g., to replace the initial test license by a final license or to upgrade the currently installed license to a larger number of users. 62
BSCW 4.2 Administration Manual
Clicking on this button shows the following form:
You have to fill in the required fields in this form and submit it. Further details about the license acquisition process are given in section 8 below.
6.2
Administration through the bsadmin script
The primary purpose of the bsadmin script is starting and stopping the BSCW server (which cannot be done through the HTML interface since the HMTL interface requires already a running server), starting the garbage collector and executing the workspace report function. Garbage collector and workspace report are normally triggered on a regular basis, e.g., by cron jobs on Unix systems or by the task scheduler on Windows 2003/XP/2000/NT systems. Therefore, the normal usage of the bsadmin script is only as: bsadmin start bsadmin stop bsadmin garbage
In addition, the script can be used for a number of used administration functions. For historical reasons the bsadmin script contains also a number of functions which can (and should!) be carried out through the HTML interface. Furthermore, it provides features which are used during software developments of the BSCW server software, e.g., for debugging purposes. Since these functions are only useful for the BSCW software developers but not for the normal BSCW server administrators, they are not explained below. When using the bsadmin command without any arguments, it displays the list of possible arguments as follows:
check configuration & make directories (I) check for missing files, [-l] long, [-r] recover/remove documents change user password remove unowned objects from anonymous home and clipboard creates an Apache Web Server configuration file configures the IIS for the BSCW server (*) configure timezone data convert BSCW Store from former versions (I) creates a BSCW catalog for the Microsoft Index Server (**) generate SWISH++ index (***) database check, [-r] repair, [-e] events, [-p] passwords find (all) modules in which classes are looked up (D) find (all) object ids of given classes (D) find (all) references of given objects (i.e. ids) (D) scan database file and print offset, class name and id print record sizes in database file BSCW_Store (D) print a summary of all classes in the database find an artifact e.g. :user/workspace/folder/.../doc check filetree for obsolete files and directories BSCW document / owner statistics / owner files BSCW garbage collector get configuration info from config.py generates an index page for the script directories print keytable of database server (D) load all objects (can take a long time) Slapd shell backend to BSCW change user ldap binding(s) Export users to LDIF format Requests a new license list BSCW documents make a new (intranet) anonymous user add or remove users from workspaces Creates folders email event notification to users print offset table of database server (D) user disk quotas commands registration of email addresses and new users modify report configuration rename a user remove (unqueue) all events older than n days remove a user remove bscw documents given by filepath remove objects from waste baskets add, edit or assign roles start BSCW local servers stop BSCW local servers synchronizes BSCW folder with file system directories updates configuration files with new defaults (I) list users and mail addresses prints a workspace statistic
The commands marked with (I) are normally used during installation only and are invoked automatically. The commands marked with (D) provide debugging information (do not use without advice from [email protected], otherwise you may damage your database). 64
BSCW 4.2 Administration Manual
(*) (**) (***)
only in Windows 2003/XP/2000/NT only if package MSindex is installed only if the package SWISHPPindex is installed
6.3
User administration
The BSCW server can be configured to allow
self-registration by users
registration of new users only by the system administrator and possibly other authorised persons.
The variable MAY_REGISTER in the BSCW instance configuration file (/src/config.py, see section 5.1) specifies which of the registration modes shall apply. When self-registration is enabled, the name space of legal email addresses may be restricted by using the variable RESTRICT_MAIL. Note that there are two forms of self-registration:
A user may enter his own email address to become a newly registered user of a BSCW server.
An already registered user may invite another person by using his or her email address.
In principle, a registered BSCW user is identified by his email address, i.e., a particular email address specifies exactly one BSCW user. Therefore, the “creation” of a new BSCW user starts with the specification of an email address, either through self-registration or by the system administrator through the administrator interface described in the preceding sections. The specification of an email address for a user is the first step of the registration process. The second step is the allocation of a user name and password to this email address. After the first step and before the execution of the second step an email address is called pending. For self-registration the BSCW server sends an email message with a “token” (the registration URL) to the specified email address that allows the execution of the second step (or the resetting of a password, see below). If the email message cannot be delivered (e.g., because the email address was wrong), the intended recipient will never receive this email and therefore cannot carry out the second step of the registration process, i.e., the email address remains pending forever. This twostep procedure ensures that email addresses of registered users are always correct, unless a user looses his or her email account later without providing a new email address. In this case the system administrator may correct wrong email addresses through the administration interface. If an email addresses remain pending because email messages cannot be delivered to the given address (this may be annoying for the system administrator since he has to take care of the bounced emails) the system administrator can set such an email address to bounced. This has two effects: firstly, the respective addresses will not produce any bounced emails anymore since the BSCW server filters all outgoing email messages against the bounced addresses list. Secondly, the BSCW server does not allow the first step of the registration process for this email address anymore. This second effect can also be used to exclude particular persons from using a BSCW server: If the system administrator sets a particular email address to bounced, the user associated with this email address cannot login to the server anymore. Furthermore, this particular user can also not re-register with the server anymore using this bounced email address. In the case of user registration through system administrators (see section. 6.1 or 6.2), they should be careful when entering the email address of new users since the verification process for the email addresses as in the case of self-registration is not carried out. Erroneous addresses would only be detected when the BSCW server sends an email message to such an address, assuming that someone takes care of bounced email messages. In the case that bounced email addresses are deleted automatically (some mail servers are configured that way), such erroneous addresses may 65
BSCW 4.2 Administration Manual
not be detected at all. If, in the case of self-registration, a user enters an email message that is already associated with a registered user, the BSCW server acts as follows:
If the user wants to register as a new user from the registration page, the system assumes that the respective user has forgotten his or her password. It therefore sends an email message to the email address, which allows the selection of a new password.
If the user wants to invite another user to this server, the system assumes that the user was not aware that the other user was already registered. The system therefore replaces the invited user’s email address by the invited user’s login name.
6.3.1
Additional anonymous users
Additionally to user 'anonymous', more anonymous users can be registered. Access to these anonymous accounts are also not controlled by authentication, but may be restricted by means of HTTP server configuration, just as in the case of user 'anonymous'. This way different levels of access control can be implemented, from unrestricted public access to anonymous intranet or even anonymous subnet access. Adding an additional anonymous user requires:
its creation with the bsadmin script,
specification of an associated CGI script,
configuration of the Web server.
Note: The additional anonymous users may be removed in contrast to user 'anonymous'. 1. The creation of a new anonymous user must be accompanied by a adding a new entry in the SCRITPS dictionary in the central configuration specification (/src/config.py). Select as key a new prefix for a directory mapping in the Web server and specify a tuple of the username, the directory (normally '../cgi'), the standard scripts and further scripts. For example: SCRIPTS = { '/bscw/':
This must be set before calling the bsadmin make_anonuser in step 2! 2. Then an additional anonymous user is created with the command bsadmin make_anonuser <username>
This registers a new user "username" for anonymous login (no authentication, no associated email address, restricted access rights), for example: bsadmin make_anonuser intranet
3. Furthermore, you have to configure your Web server to handle restricted access to the anonymous prefix. For the Apache Web server, you would have to add in the file httpd.conf: ScriptAlias
/intra
.../BSCW/server/cgi
66
BSCW 4.2 Administration Manual # use CGI scripts Options ExecCGI AddHandler cgi-script .cgi # set index file DirectoryIndex index.html default.htm # client access Order deny,allow Deny from all #
some dedicated IP numbers may access this directory
Allow from 121.23.45.67 Allow from 121.23.45.89 # ...
To
generate
this
configuration automatically within your /apache.conf file you have to create a /u_<username>.txt file which contains the Allow from directives for the allowed IP address ranges which may access the additional anonymous user prefix. Following the above example, create the file /u_intranet.txt and enter the following Allow from directives: Allow from 121.23.45.67 Allow from 121.23.45.89
Now execute the bsadmin conf_apache command to generate a new /apache.conf file and restart your Apache HTTP server. After these three steps have been carried out, access to the workspaces of the newly created anonymous accounts are via the URLs: http:///intra/bscw.cgi
6.3.2
User registration with bsadmin register
For the administration of users and their email addresses the bsadmin script offers the following functionality: bsadmin register bsadmin register bsadmin register bsadmin register bsadmin register bsadmin register bsadmin register bsadmin register bsadmin register bsadmin register bsadmin register bsadmin register bsadmin register [-o nday]
6.4
info about mail address print all mail addresses print all bounced addresses (-d: delete) set bounced create pending mail address delete print username / / rename (change address) print all pending addresses (-d: delete) set pending register new user print all allocated addresses allocate mail address to user consider only objects with a modification date before 'nday' days
BSCW has an API (application programmers interface) based on XML-RPC, called X-BSCW. XBSCW provides (almost) all operations which a registered user may invoke in BSCW's normal Web user interface. This allows, e.g., an integration of BSCW with existing legacy applications. The obvious exceptions are operations which refer to the HTML interface itself, e.g. hiding/showing columns, folding out of description texts, manipulating fonts or colors. Otherwise, all operations which are feasible at the HTML interface of BSCW are available in X-BSCW as well. In order to use the X-BSCW API it must be explicitly enabled by setting the ACCEPT_XML_RPC variable to 1 in the BSCW instance configuration file /src/config.py). If ACCEPT_XML_RPC set to 0 (default), XML-RPC requests will be rejected by BSCW with the HTTP error code 501: content_unsupported. A detailed description of the API can be found in the X-BSCW API Manual.
6.5
User Notification Services (UNO)
The user notification services (UNO) perform the following tasks (depending on the configuration settings in the BSCW instance configuration file /src/config.py):
sending periodical workspace activity reports via email to give the users an overview about recent activities in a specific time period (e.g. daily)
sending direct email notifictions to inform the users about recent events
provide online users with real-time awareness information via the “Monitor Applet”
Using the user notification services a BSCW user does not need to contact its BSCW server(s) so often to check for new events. If the user notification services are activated, the users' event preference page provides a column for subscription of the “Daily Report”, the “Direct Email” notification or the “Monitor Applet” (depending on the UNO service configuration). To activate the user notification services the BSCW administrator has to start the additional UNO server (bs_servuno) in the SERVERS list in config.py: 1. On Unix using unix domain sockets (AF_UNIX; preferred on Unix): SERVERS = [ ('../data/ServUno', 'bs_servuno', 'cl_servublk'), ]
2. On Windows/Unix using TCP/IP sockets (AF_INET): SERVERS = [ (('localhost', 12866), 'bs_servuno', 'cl_servinet'), ]
The UNO server sends HTTP requests to the BSCW server. In the default configuration it connects the BSCW server via its SERVER_ROOT. If you defined a HTTPS server root or your server root is not resolvable on the local BSCW server machine, you need to define an additional (virtual) web server and to set the server root of this webserver in the configuration variable SERV_UNO_ROOT (for Apache HTTP server configuration hints see section 3.3.1 (Unix) or section 4.5.3 (Windows)). Note: This setting will start and stop the UNO server automatically with the BSCW database server. To not interfere with the user notification service the workspace activity report configuration of versions prior to BSCW 4.2 must be disbabled by removing the crontab (Unix) or the task 68
BSCW 4.2 Administration Manual
scheduler (Windows) entry for bsadmin notify -a. Note: Enable the user notification services after the upgrade to BSCW 4.2 The following variables have to be set for the configuration of the user notification services: SERV_UNO_ROOT is set to the SERVER_ROOT by default. However when SSL is used then another non-SSL (i.e.) HTTP access to the local BSCW server must be given here. 'http://localhost' might be a good choice in this case. Attention: If the SERVER_ADMINS_IP list is not empty, the IP address of the SERVER_ROOT resp. SERV_UNO_ROOT web server must be contained in the SERVER_ADMINS_IP list, eg. SERVER_ADMINS_IP = [ '1.2.3.4',
# administrator IP address
'127.0.0.1',
# SERV_UNO_ROOT = 'http://localhost' or
'193.175.161.100',
# SERVER_ROOT = 'http://bscw.fit.fhg.de'
]
SERV_UNO_STATE defines a file name for saving the state of the UNO service. The file is
written, when the UNO is stopped and read when the server is started again.
SERV_UNO_TIMES contains a dictionary of fine tuning parameters for the UNO service; for details see the server instance configuration file config.py.
WSREPORT = 1 enables the daily workspace report
WSREPORT_DIRECT = 1 enables the direct email notification
the default subscription for all users is defined by the AUTOSUBSCRIBE_REPORT flag. By default no report is sent to new users, each user may decide to subscribe to the workspace report by her/himself. The server administrator can change this behavior by setting the flag AUTOSUBSCRIBE_REPORT = 1
If this is enabled new users will automatically subscribed to the report service (each user may then unsubscribe from the service). Note: The SERVER_ROOT variable must be properly set in the instance configuration file for the workspace report feature to work correctly. See section 3.3.2 BSCW provides a real-time awareness service (AWS), which basically allows users to receive notifications about BSCW events in real-time, i.e. when they occur in the system. Moreover it allows users to see who (of their collaborators) is currently online. The AWS is provided through the BSCW Monitor Applet (JMonitor) which can be launched from context menu on users' BSCW home folder. To enable the AWS set the flag AW_MONITOR_ENABLED = 1
The Monitor Applet requires the BSCW XMLRPC-API. Setting AW_MONITOR_ENABLED = 1 mandatory requires to enable the BSCW XMLRPC-API by setting ACCEPT_XML_RPC = 1 Note: See the User Notification Services (UNO) section in your instance configuration file for more details.
69
BSCW 4.2 Administration Manual
6.6
WebDAV
WebDAV stands for “Web-based Distributed Authoring and Versioning”. It is a set of extensions to the HTTP protocol (IETF RFC 2538) which allows users to collaboratively edit and manage files on remote Web servers, i.e., some of the BSCW features (e.g., document upload to a BSCW server or renaming of a document on a BSCW server) are also supported by the WebDAV protocol. Starting with Version 4.2 BSCW supports (a subset of) the WebDAV protocol. This means that some of the BSCW operations which are available via a Web browser and through the HTML interface of BSCW, are now also available via WebDAV clients (http://www.webdav.org/) for software supporting the WebDAV standard). Note: There are many WebDAV clients available and we could only test a small subset of them with BSCW WebDAV support. From our tests we assume that not all WebDAV clients fully conform with the WebDAV specifications, i.e., you may have problems when using a particular WebDAV client with BSCW.
6.6.1
Installation
The BSCW WebDAV interface requires the installation of the following components: 1. BSCW WebDAV shows best results with Apache HTTP server version 2.0. Install at least Apache 2.0.52 (cf. security advisory in section 3.3.1 (Unix) / 4.5.3 (Windows)). Ensure the mod_rewrite and the mod_headers Apache HTTP server dynamic shared object (DSO) modules are installed with your Apache HTTP server (which is the default). For building and installation instructions refer the INSTALLATION file in the Apache HTTP server distribution; we provide here only a rough sketch:
Unpack the source distribution of Apache HTTP server version 2.0.52, e.g. $ gunzip < httpd-2.0.52.tar.gz | tar xf -
Build and install Apache HTTP server version 2.0.52 (as described in the INSTALL file) $ cd httpd-2.0.52 $ configure –enable-mods-shared=all –-enable-shared=max $ make $ make install
Refer section 3.3.1 for Unix or section 4.5.3 for Windows 2. Install the PyXML package for your Python installation. The PyXML package is a collection of libraries to process XML with Python. Download PyXML from SourceForge http://pyxml.sourceforge.net/ and install the package:
unpack the source distribution of PyXML, e.g. $ gunzip < PyXML-0.8.3.tar.gz | tar xf -
build and install PyXML (as described in the README file) $ cd PyXML-0.8.3 $ python setup.py build $ python setup.py install
70
BSCW 4.2 Administration Manual
After installation of the PyXML package run bsadmin conf_apache (with BSCW user ID) $ cd $ ./bsadmin conf_apache
This creates a new /apache.conf file. Include this file in your httpd.conf file (cf. section 3.3.1 (Unix) / 4.5.3 (Windows)).
6.6.2
Microsoft Support for WebDAV
More recent Microsoft Windows and MS Office versions (Windows/Office 2000, XP) provide WebDAV support. This allows the following applications: 1. Opening of BSCW workspaces within Windows Explorer. Proceed as follows:
Select “My Network Places” (either from your desktop or within Windows Explorer).
Select “Add Network Place”
Enter the URL of your BSCW home folder (or a sub-folder). This has the form http://bscw.domain.org/bscw/bscw.cgi/0/9620 http://bscw.domain.org/bscw/bscw.cgi/:Smith.
You will then be prompted for your BSCW user name and password.
Click “Finish”.
You may then browse with Windows Explorer through your BSCW workspaces in the same way in which you browse through the file system on your local computer. You may also "drag and drop" files from your local file system to BSCW folders or vice versa. When clicking the right mouse button, you may carry out several actions such as deleting or renaming an object. 2. Editing of MS Office files in BSCW workspaces. Proceed as follows:
From within Windows Explorer (see previous example) select, e.g., a MS Word document within a BSCW folder.
Open the document by double-clicking it.
Edit the Word document as usual.
After editing “Save” the document. The document will be saved back into the BSCW folder.
Known Problems The Microsoft implementation of WebDAV is not fully compliant with the WebDAV RFC which may cause some problems. The following problems are already known:
The RFC requests a special encoding of spaces and non-alphanumeric characters. MS Internet Explorer and Windows Explorer do not process such characters correctly. (Recommendation: Use only alphanumeric names (without spaces) for BSCW objects when MS Internet Explorer or Windows Explorer shall be used as WebDAV clients).
Dialogue boxes and error messages are sometimes misleading.
Drag and Drop within the same directory results in a copy operation.
Please inform us if you observe additional problems.
71
BSCW 4.2 Administration Manual
6.7
LDAP
The Lightweight Directory Access Protocol (LDAP) is a protocol for accessing online directory services. It runs directly over TCP, and can be used to access a standalone LDAP directory service or to access a directory service that is back-ended by X.500. The BSCW system implements an interface to LDAP servers based on the Python-LDAP module. Python-LDAP wraps an underlying LDAP C library that provides an RFC 1823 API, such as OpenLDAP (http://www.openldap.org/).
6.7.1
Installation
To install the BSCW LDAP package 1. The BSCE ldap package needs the Python-LDAP module. Python-LDAP provides functionality for accessing LDAP servers from Python. It wraps an underlying LDAP C library that provides an RFC 1823 API, such as OpenLDAP 2.x (http://www.openldap.org/) Download Python-LDAP at http://python-ldap.sourceforge.net/ and install the package:
unpack the source distribution of Python-LDAP, e.g. $ gunzip < python-ldap-2.0.2.tar.gz | tar xf -
build and install Python-LDAP (as described in the README file) $ cd python-ldap-2.0.2 $ vi setup.cfg $ python setup.py build $ python setup.py install
This installs the shared library _ldap.so (among other things) in your standard Python library path. 2. Copy the file default/config_ldap.py to config_ldap.py: $ cd /packages/ldap/src $ cp default/config_ldap.py config_ldap.py
3. To enable the BSCW LDAP package add the package directory to the PACKAGES list in /src/config.py: PACKAGES = [ '../packages/ldap', ]
4. Adapt src/config_ldap.py to your needs, especially the “hosts” map and the “auto_registration” list:
hosts is a dictionary mapping
distinguished names (DNs) -> hostname[:portnumber] When an LDAP object is searched (referred by a DN), this table is looked up for a corresponding LDAP server address. The DNs should be in a 'canonical' form (lower case, no spaces before or after ',' and '=').
auto_registration is a list (or tuple) of patterns for generation of DNs from user names. An user is automatically registered with BSCW during login if all of the following items apply:
1. direct
HTTP
server
LDAP
authentication 72
(recommended;
see
notes
for
BSCW 4.2 Administration Manual use_ldap_passwords below) or COOKIE_AUTHENTICATION is enabled (see BSCW
configuration), 2. the user with the given login name is not already a registered BSCW user, 3. one of the generated DNs can be found in the corresponding LDAP server, 4. the resulting LDAP object has an objectClass as defined in the person_classes list (default: person_classes = [ 'person', ] , 5. and the user can “bind” (authenticate) to the resulting LDAP object with the given password. When a BSCW user is registered in this way, all BSCW relevant attributes (i.e. the user details) are set by corresponding LDAP object attributes (see also update_list in bs_ldap.py for attribute name translation). A special 'ldap_bind' attribute of the BSCW user object refers to the users' DN. Furthermore, if the auto_registration list is not empty and direct HTTP server LDAP authentication or COOKIE_AUTHENTICATION is enabled, then all BSCW users that have an LDAP binding set are authenticated via the LDAP server. During login, the BSCW server checks the success of a bind operation to the user's DN with the given password (see notes for use_ldap_passwords below).
auto_registration_roles defines initial roles for automatically registered users. The list consists of pairs ('attribute=value', role)
Note: the role must be assignable for user objects i.e. it must appear in the list cl_action.user_roles. Note: at the moment the 'attribute=value' string is only looked up in the DN (user.ldap_bind) of the user. The LDAP attributes of the user are ignored. This might be changed in the future.
use_ldap_passwords defines how BSCW handles users with LDAP binding and local BSCW users (without LDAP binding):
If use_ldap_passwords is 1 then for all users passwords are verified against the LDAPserver. Hence an existing user who is not found on an LDAP server cannot login to the system anymore.
If use_ldap_passwords is 2 then the user password is verified against the LDAP-server only for users with a LDAP binding or users found on a LDAP server. Hence an existing local BSCW user who is not found on a LDAP server and who do not have a LDAP binding can still login to the system.
If use_ldap_passwords is 3 then the user password is verified against the LDAP-server only for users that have a LDAP binding
Note: BSCW does password checking by LDAP only if the BSCW server and not the HTTP server does authentication, e.g. when cookie authentication is enabeled or BSCW gets the HTTP_AUTHORIZATION value). Because this is not a very fast way to do authentication, it is strongly recommended to configure the HTTP server to do direct LDAP authentication (e.g. via the Apache HTTP server mod_ldap (Apache 2.0) or auth_ldap (Apache 1.3) module) instead of setting use_ldap_passwords = 1 which requires all users to pass LDAP authentication. Note: If the Apache HTTP Server mod_ldap (Apache 2.0) or auth_ldap (Apache 1.3) module is used and BSCW should be able to change passwords at the LDAP-server use_ldap_passwords must be set to 3, otherwise the BSCW change password action 73
BSCW 4.2 Administration Manual
interferes with the mod_ldap resp. auth_ldap modules internal password cache.
ldap_searches defines a list of member search options (id, pattern) or (id, pattern, rdnlist) for the workspace invite member action (op_addmb):
id is an unique identifier for the search packages/ldap/messages/*/lg_msgconfig.py.
and
must
be
translated
in
pattern is a LDAP query where '%(query)s' is replaced by the user input of the
addmb search form
rdnlist defines an optional filter for a relative DN type, which allows to additionally
remove query results which do not match the given RDN value list Examples of LDAP queries:
search subtree of defined base DN(s) for the given query: ('mb_search_ldap_uid', 'cn=*%(query)s*'), ('mb_search_ldap_uid', '(|(cn=*%(query)s*)(uid=*%(query)s*))'),
search subtree of defined base DN(s) for query 'ou=*%(query)s*' and remove results which relative DN of type 'ou' does not match the given list ['sales', 'external']: ('mb_search_ldap_org', '(ou=*%(query)s*)', ('ou', ['sales', 'extern'])),
6.7.2
LDAP Browser
After installation of the LDAP package, a small “organisational browser” is enabled (op_ldap.py in this package). When opening a user info window (e.g. by clicking on a user name in the web interface) the user’s LDAP binding (if defined) is shown. By selecting the link of the ldap binding field the user information (as retrieved from the LDAP server) is displayed in the organisational browser. If the LDAP package is installed and activated, the ‘Goto’-Menu contains an entry ‘Organisation Info’ that invokes the organisational browser. The browser connects to the LDAP servers in the hosts map and allows operation on LDAP objects. The operations search, bind, view, and attribute editing are supported. Furthermore an anonymous user is allowed to register as a BSCW user with his LDAP user password and a BSCW administrator might also register other users, if he knows the respective LDAP user passwords. Note: ORG_INFO_URL must not be set in /src/config.py, because this will override the handler invoked by the ‘Organisation Info’ menu entry. Note: You need basic knowledge of directory services in general and especially need to know some details about LDAP in order to configure BSCW for LDAP. Besides the more technical IETF RFCs and Drafts about LDAP – which can be found at http://www.ietf.org/ – we suggest to read the IBM Redbook: Understanding LDAP (SG-244986, June 1998), available at http://www.redbooks.ibm.com/.
6.8
Web Search with Google Web APIs service
To enable the Google search engine within the BSCW internet search engines (for details see the [File > Search > Internet] menu) BSCW must be able to access the Google Web APIs service. To access the Google Web APIs service a Google account must be created to obtain a license key. The Google Account and license key entitles the account
holder
to
1,000
automated
queries
74
per
day.
Please
open
the
page
BSCW 4.2 Administration Manual http://www.google.com/apis/ and apply for a license key. Enter the provided key in the googleKEY directive of the BSCW Google Web Search configuration file ./src/bs_config.py: googleKEY
= '12345'
# key provided by Google
The Google Web API uses the SOAP and WSDL standards. To access this functionality the additional Python packages (already installed in the BSCW Google Web Search ./lib directory) are used:
fpconst-0.7.0:
./lib/fpconst.py
SOAPpy-0.11.6 (apdopted version):
./lib/SOAPpy/
Additionally the Python package PyXML is required. The PyXML package is a collection of libraries to process XML with Python. Download PyXML version 0.8.3 or better from SourceForge (http://pyxml.sourceforge.net/) and install the package: unpack the source distribution of PyXML, e.g.
# gunzip < PyXML-0.8.3.tar.gz | tar xf -
build and install PyXML (as described in the README file)
# cd PyXML-0.8.3 # python setup.py install
6.9
Quota - Disk Usage Limitation
BSCW quota individually allows to restrict the amount of disk usage for users. In order to enable the BSCW quota system, the administrator has to define in a first step limit classes. Afterwards quota can be turned on for all or individual users by assigning a limit class to this users. In previous BSCW versions the disk space allocated to each user (quota) was computed as follows:
When a user created an object, the disk space used by the object was added to the quota of this user.
In particular, when user A created an object in a folder that was owned by user B, the quota of user A was affected, not the quota of user B.
A possible side effect: If user A later was not able to access this folder owned by user B anymore (because he was removed from the members' list), user A could not access (e.g., delete) this object anymore although its disk space still contributed to user A's quota.
This led often to confusion since users had a high quota (or even exceeded the quota permitted by the system administrator) although the objects they could see in their folders consumed much less disk space than their actual quota. In BSCW version 4.2 the disk space allocated to each user (quota) is computed as follows:
When a user creates an object, the disk space used by the object is added to the quota of the owner of the folder wherein the object is created.
In particular, when user A creates an object in a folder that is owned by user B, the quota of user B is affected, not the quota of user A.
If the owner of a folder is removed from its members' list (either by others or by himself or herself), the ownership of the folder and of the objects therein is transfered to another person 75
BSCW 4.2 Administration Manual
who still has access to this folder.
This new procedure for computing the quota of users has the effect that users can always access all objects that contribute to their quota.
Note: By default quota is now enabled for the anonymous user to avoid the assignment of any resources to the anonymous user. To explicitly disable quota limitation for the anonymous user run the command bsadmin quota off anonymous. Alternatively you may assign a new limit class to the anonymous user with the command bsadmin quota on -c anonymous. Quota is accessed by the BSCW administrator via the bsadmin quota command line interface. In general the bsadmin quota command supports the following four options: bsadmin quota limit
defines and lists all limit classes;
bsadmin quota { on | off }
enables/disables quotas for all or individual users;
bsadmin quota { check |fix }
checks or fixes disk and object usage for all users;
bsadmin quota { report | class } report quota for users or limit classes
The bsadmin quota command executed without any argument displays the usage information: $ ./bsadmin quota usage: bsadmin quota bsadmin quota { check | fix }