2. Installation of the BSCW server

As a prerequisite for installing a BSCW server you need either a server host running a Unix system - the BSCW server is supported on Linux and BSD.

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 Intel Core/Xeon or a AMD EPYC/Ryzen (>3,5 GHz) with at least 6 cores, 16 GB RAM and 500 GB disk space should provide an 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 website at https://www.python.org/). Therefore, besides the BSCW software, the installation of the BSCW server requires

  • a Web Server

  • the Node.js (v18 LTS) an event driven JavaScript runtime

  • a Python 3.8, 3.9, 3.10, or 3.11 interpreter

  • Python Jinja2 template engine

  • (optional) extensions for Python (pylucene, ldap3)

  • (optional) memcached to speed-up large folder handling (Unix)

  • (optional) converter software for the BSCW preview feature, see sections 3.3 Software for BSCW Preview (Unix) for details

The BSCW server can be installed on a CGI compliant Web server, e.g. the Apache HTTP server.

Additionally the Node.js runtime environment is required, which pushes occurring change notifications almost in real-time to active users, using a WebSocket-based events server. The Node.js runtime environment is freely available at the Node.js Foundation website (https://nodejs.org/en/download/). Best use the Node.js LTS release.

Finally a Python 3 interpreter and the Python Jinja2 template engine is required to run the BSCW software. The Python 3 interpreter is freely available on the Python Software Foundation website (https://www.python.org/downloads/). We currently support versions 3.8 to 3.11 of the Python interpreter only.

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.

Note

Please also consult chapter 9 Frequently Asked Questions (FAQ) in this manual - or the online version at https://www.bscw.de/en/support/ - for common and platform-specific installation questions; if you have a problem not addressed there, send an email to support@orbiteam.de.

2.2. Security considerations

Newly installed BSCW instances do have the following possibly security relevant features enabled by default:

  1. Enabled user self-registration

    A newly installed BSCW instance allows every registered user to create a new user account by registering a new email address. This is probably not in all situations the desired behavior. If you do not want to allow the self-registration of new user accounts by registered users, you have to disable this feature by setting in the instance configuration file <bscw-runtime-path>/conf/config.py the directive MAY_REGISTER to a non empty list. See the directive description in the instance configuration file for details.

  2. Enabled “public space”

    By default BSCW allows users in the “manager” role to publish the contents of a folder in a “public space”, which can be accessed by everyone over the World-Wide-Web without being a registered user of the server. Recently misuse of this feature was reported (users published inappropriate content). To disable the public space for all users see section 6.5 Public space deactivation.

  3. Environment with credential information (Unix)

    Depending on the authentication method the user credentials are passed via an environment variable (Basic/Cookie authentication) in plain text to the bscw.cgi process. Even if the credential information is removed immediately from the environment this might impose a security problem on systems running other applications with the user-id of the Apache web server. In this case such an application may disclose user names and passwords from the environment of a running bscw.cgi process.

2.3. EU - General Data Protection Regulation

The General Data Protection Regulation (GDPR) (EU) 2016/679 is a regulation in EU law on data protection and privacy for all individuals within the European Union.

The GDPR aims primarily to give control to citizens and residents over their personal data and to simplify the regulatory environment for international business by unifying the regulation within the EU.

According to the GDPR BSCW has introduced the following measures:

  • In order to simplify the information about processed personal data, the recording of events has been extended for user accounts accordingly.

  • In addition to the user [i]nfo page on the web interface, for each user account an export of personal data is possible with the command line program bsadmin userdata in a machine-readable format (JSON).

  • After the deletion of an user account, an audit log (history) of events is saved to an external file in the directory <bscw-runtime-path>/var/data/rmuserarc to document all processing operations (including deletion).

    This audit log file is automatically removed at the end of the following year (see § 76 BDSG-Protokollierung (4)) by the /etc/cron.daily/bscw Cron script (see BSCW Startup for details).

With the legal validity of the EU - General Data Protection Regulation (GDPR), it will be necessary to provide a data protection declaration which sets out what personal information is collected during the use of the BSCW system and how these data are used.

You can find a template of a data protection declaration for BSCW on our website

https://www.bscw.de/files/dataprotection/Dataprotectiondeclaration-BSCW.docx
https://www.bscw.de/files/dataprotection/Datenschutzerklaerung-BSCW.docx

or in the BSCW software distribution in the directory <$HOME>/lib/bscw-7.5.4-<rev>-py3*/doc/dataprotection/:

* Dataprotectiondeclaration-BSCW.docx
* Datenschutzerklaerung-BSCW.docx

Please edit the data protection declaration accordingly (e.g. adopt controller contact, organisation address and complete which data is required for BSCW registration) and create a PDF document which may be located in the BSCW runtime path <bscw-runtime-path>/var/www at:

$ cp Dataprotectiondeclaration-BSCW.pdf Datenschutzerklaerung-BSCW.pdf \
  <bscw-runtime-path>/var/www

Next define the runtime directives in the instance configuration file <bscw-runtime-path>/conf/config.py:

PRIVACY_POLICY = '/pub/Dataprotectiondeclaration-BSCW.pdf'
PRIVACY_POLICY_DE = '/pub/Datenschutzerklaerung-BSCW.pdf'

Note

/pub/ is the default “public” path, you can replace it by your SERVER_HOME (which is usually /).

If the PRIVACY_POLICY directives are defined the self-registration procedure requires new users to agree with this data protection declaration to complete the registration.

Afterwards recreate the BSCW instance index pages to reflect the changes with:

$ bin/bsadmin index_page

2.4. Upgrading to BSCW 7.5.4

If you are installing BSCW for the first time please refer to the installation section (Installation procedure for Unix). For upgrading, you essentially proceed the same way as shown in the installation section.

Note

  • If you are using the Apache HTTP server you must restart the web server after each upgrade.

  • It is possible to upgrade your Python version before a BSCW upgrade.

  • To list all installed BSCW instances on the installation host run bsadmin manage_servers -l:

    $ ./bin/bsadmin manage_servers -l
/opt/bscw/srv/bscw.domain.org:   BSCW 5.2.6

Substitute <bscw-runtime-path> 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:

Warning

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 license@orbiteam.de for details OR

  • 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 license@orbiteam.de for details.

See also

Upgrading on Unix to consider the following advices when upgrading:

When upgrading from BSCW 7.5.3 or lower

Following penetration tests by the BSI and by T-Systems, further security improvements were made. In particular, the included jQuery javascript library has been updated.

Please update the Apache HTTP server virtual host definition for your BSCW service to define additional security header fields. For further details please refer to the Security Header section in <bscw-runtime-path>/conf/apache24/site.conf.

The the real-time conference service(s) support now JSON web token authentication (RFC 7519). See the CONFERENCE_PROVIDER directive for details.

When upgrading from BSCW 7.4.4 or lower

The configuration of the real-time conference has been unified. This requires the transfer of the previous COMMUNICATION_SERVER setting into the CONFERENCE_HOST variable (prefixed with ‘https://’). Furthermore, the Apache modules authn_core, authz_core, filter, proxy, proxy_http, proxy_wstunnel, ssl and substitute must be activated.

After setting CONFERENCE_HOST run bsadmin conf_apache -T` to create an access token file conf/apache24/service_token.conf.

When upgrading from BSCW 7.4.3 or lower

Further critical security vulnerabilities have been fixed during an intensive security audit. Please update your BSCW instance immediately to at least version 7.4.4 (many thanks to stuxxn@red-shell.dev). Attention: The found security vulnerabilities will be published with CVE reference at https://www.bscw.de/security-fixes/ starting 2021-11-29.

When upgrading from BSCW 7.4.2 or lower

Please upgrade your BSCW instance to at least version 7.4.3.

(Security) A critical vulnerability has been discovered allowing remote code execution by authenticated users, see CVE-2021-36359.

(Security) A possible exploit of a security vulnerability in the external reportlab library has been fixed. The upgrade procedure may disable the BSCW package exportpdf. To re-enable it, install a reportlab version >= 3.5.55 and run bsadmin package -e exportpdf.

The resource consumption of quotas should be recalculated by running bsadmin dbcheck repair -f q because an error occurred that counted versioned documents twice.

When upgrading from BSCW 7.4.1 or lower

(Security) The registration token in a registration email has been strengthened. Note: previously sent registration tokens become invalid.

When upgrading from BSCW 7.2.1 or lower

(Security) The Apache HTTP configuration has been extended with the following HTTP security headers: X-Content-Type-Options, Referrer-Policy, Strict-Transport-Security. These headers are automatically enabled in the Apache HTTP server virtual host configuration conf/apache24/site.conf; please make sure to apply these changes to your current configuration.

For new BSCW instances the default values of BADPASS and ALLOW_MAIL_UNLOCK have been changed. For existing instances the values are not adopted, so it is recommended to manually set the values in <bscw-runtime-path>/conf/config.py to BADPASS = 10 and ALLOW_MAIL_UNLOCK = True.

A new AUTH_TOKEN_EXP configuration directive has been introduced to limit the maximum validity period of a registration link, see <bscw-runtime-path>/conf/config.py for details.

The HTML/PDF converter PhantomJS has been replaced in favour to WeasyPrint. If possible, you should install WeasyPrint before updating BSCW, see Software for BSCW Preview Unix

When upgrading from BSCW 7.1.0 or lower

The BSCW 7.5 release requires the installation of a Node.js runtime environment. See system requirements for Unix systems.

A new “dark theme” has been introduced. To make it available to all users the THEMES list in the instance configuration file <bscw-runtime-path>/conf/config.py has to be extended with an 'default/default_dark' entry as follows:

THEMES = [
   'default/default',
   'default/default_dark',
]

When upgrading from BSCW 5.2.6 or lower

BSCW 7.5 does not support all (500+) features from BSCW 5 (or earlier) versions. If you are upgrading from a BSCW 5 version, it is advisable to run the bsadmin migrationchecker to see if all objects can be migrated. Please contact support@orbiteam.de for further assistance.

Native Windows support has been discontinued for BSCW 7. It is possible to run BSCW 7 on a Windows operating system using virtualizations like VMware, Hyper-V, Docker container or WSL.

The upgrade procedure converts the BSCW persistent data store to the Python 3 object serialization format and reverses the order of the object event queues. This process may require a large amount of (additional) memory. Before starting the upgrade procedure it is advisable to perform the following steps:

  • perform a garbage collection on the originating system and save the backup storage

    $ cd <runtime>
$ bin/bsadmin garbage
...
$ mv var/data/Backup var/data/Backup52

  • BSCW 7.5 requires Python 3.8, 3.9, 3.10, or 3.11. To upgrade, one of the supported Python 3 versions must first be available on the BSCW target system. It is recommended to migrate your Python 2 based BSCW instance to a new distribution with native support for the selected Python 3 version. See system requirements for Unix systems for a detailed description of required software packages.

    If you use Berkeley DB to maintain BSCW database tables (DBMOD_TAB = 'bsddb4') you have to install the Python bindings for Berkeley DB (bsddb3):

    • Debian based systems:

      $ su -
# apt install python3-bsddb3

    • EL 8/9 based systems:

      $ su -
# dnf install libdb-devel
# pip-3.[89] install bsddb3

  • disable all user access to the BSCW server to avoid interference between users and the upgrade process by stopping the web service

  • start the upgrade procedure

    $ sudo su -
# cd bscw-|relmajor|.*-<hash>-py3*
# ./install.sh

Note

Depending on the size of the BSCW instance database, the upgrade process requires a lot of memory and may take a long time.

After the upgrade, it is recommended

  1. to run a garbage collection:

    $ bin/bsadmin garbage

  2. to enable the pre-forking BSCW HTTP server for performance reasons

  3. to revert all event queues (depending on the size and age of the BSCW database this may require a lot of memory):

    $ bin/bsadmin fix_event_queue -F ALL

  4. to check for/fix database inconsistencies:

    $ bin/bsadmin dbcheck list   -ef ' b c e h m n q s t seeme undelete mprofile timezone'
$ bin/bsadmin dbcheck repair -ef ' b c e h m n q s t seeme undelete mprofile timezone'

  5. to initialize all subtree caches for chats/tasks and (optionally) to mark all entries as seen:

    $ bin/bsadmin subtreecache -mc

If the binary python package setproctitle is installed BSCW processes are displayed with more telling names. For BSCW 7.5 the setprocfile package is included for the supported Python versions.

When upgrading from BSCW 5.2.5 or lower

Following penetration tests by the BSI and by T-Systems, further security improvements were made. In particular, the included jQuery javascript library has been updated and a cross-site scripting (XSS) vulnerability in the mobile package has been fixed.

The mobile package will be disabled during the upgrade because it uses an incompatible prior jQuery version that contains unfixed vulnerabilities. This is purely a precaution, there are no known BSCW exploits.

In particular, all deprecated packages will be disabled during the upgrade: airdesktop, case, easy, mobile, sync, moin, Secure.

Please update the Apache HTTP server virtual host definition for your BSCW service to define additional security header fields. For further details please refer to the Security Header section in <bscw-runtime-path>/conf/apache24/site.conf.

When upgrading from BSCW 5.2.4 or lower

Further critical security vulnerabilities have been fixed during an intensive security audit. Please update your BSCW instance immediately to at least version 5.2.5 (many thanks to stuxxn@red-shell.dev). Attention: The found security vulnerabilities will be published with CVE reference at https://www.bscw.de/security-fixes/ starting 2021-11-29.

When upgrading from BSCW 5.2.3 or lower

(Security) A critical vulnerability has been discovered allowing remote code execution by authenticated users, see CVE-2021-36359.

(Security) A possible exploit of a security vulnerability in the external reportlab library has been fixed. The upgrade procedure may disable the BSCW package exportpdf. To re-enable it, install a reportlab version >= 3.5.55 and run bsadmin package -e exportpdf.

The resource consumption of quotas should be recalculated by running bsadmin dbcheck repair -f q because an error occurred that counted versioned documents twice.

(Security) The Apache HTTP configuration has been extended with the following HTTP security headers: X-Content-Type-Options, Referrer-Policy, Strict-Transport-Security. These headers are automatically enabled in the Apache HTTP server virtual host configuration conf/apache24/site.conf; please make sure to apply these changes to your current configuration.

For new BSCW instances the default values of BADPASS and ALLOW_MAIL_UNLOCK have been changed. For existing instances the values are not adopted, so it is recommended to manually set the values in <bscw-runtime-path>/conf/config.py to BADPASS = 10 and ALLOW_MAIL_UNLOCK = True.

A new AUTH_TOKEN_EXP configuration directive has been introduced to limit the maximum validity period of a registration link, see <bscw-runtime-path>/conf/config.py for details.

The HTML/PDF converter PhantomJS has been replaced in favour to WeasyPrint. If possible, you should install WeasyPrint before updating BSCW, see Software for BSCW Preview Unix

When upgrading from BSCW 5.2.2 or lower

If the binary python package setproctitle is installed BSCW processes are displayed with more telling names (Linux).

Due to the exchange of document MIME icons, all style sheets for website folders must be adopted using [ ‣ New ‣ Style Definition].

When upgrading from BSCW 5.2.1 or lower

The IP address parsing for the SERVER_ADMINS_IP directive has been extended to support IPv6, prefix or netmask notation; old entries must be updated accordingly. Syntactically incorrect entries are ignored.

A new version (1.4.0) of the “ZOPE External Editor, BSCW Edition” with TLS 1.3 support is available at <https://www.bscw.de/classic/#externalEditor>.

When upgrading from BSCW 5.2.0 or lower

With the legal validity of the EU - General Data Protection Regulation (GDPR), it will be necessary to provide a data protection declaration with the BSCW system (see section 2.3 EU - General Data Protection Regulation for details).

When upgrading from BSCW 5.1.9 or lower

Please note, the upgrade procedure for BSCW 5.2 overwrites the default system message for new users in the <bscw-runtime-path>/conf/msg/*/sys_msg0.html files and recreates the converter configuration <bscw-runtime-path>/conf/config_convert.py file. If you are using a customized system message or an own converter configuration you may restore your old configuration from the most recent <bscw-runtime-path>/conf/conf-<date> directory after upgrading.

BSCW 5.2 introduces a new pre-forked HTTP server which greatly speeds up the processing of requests. Load tests have shown an average performance increase of 30% compared to the traditional Apache HTTP server CGI. To enable this feature, see the description in the HTTP_LOCAL_PORT_START directive section and the BSCW http package documentation.

BSCW 5.2 Classic introduces a new, modernized layout. To provide the old BSCW 5 layout of previous versions you may append the entry 'old' to the themes definition in the instance configuration file <bscw-runtime-path>/conf/config.py, e.g.:

THEMES = (
    'bscw',
    'bw',
    'old',
)

Support for deprecated BSCW packages moin and SMS has been ended.

When upgrading from BSCW 5.1.8 or lower

The virus scan feature has been improved, virus scan is now performed asynchronously and additionally possible before download. After the upgrade virus scan must be re-enabled, please see VIRUS_CHECK for details.

Apache Tika server support has been added, please see for Unix systems section 3.3 (Apache Tika) for details.

When upgrading from BSCW 5.1.7 or lower

Due to an internal reorganisation of object deletion, it might be necessary to fix changed workspace roles. Run bsadmin dbcheck repair -f ' seeme undelete' to fix affected access rights.

When upgrading from BSCW 5.1.4 or lower

(Unix) On systems using a systemd service to start BSCW instances, the service configuration must be changed before upgrading. The following configuration directives must be added to each unit files’ “[Service]” section, e.g.:

[Service]
GuessMainPID=no
RemainAfterExit=yes

After changing a unit file the systemd configuration must be reloaded with systemctl daemon-reload as root. The BSCW installer install.sh will check and notify you if these directives are missing in a BSCW unit file.

(Unix) Due to a text extraction bug not all uploaded documents are indexed properly by the BSCW “lucene” indexer (package PyLucIndex). To index affected documents run:

$ cd <bscw-runtime-path>
$ find var/data/Text -type f -size 0 | xargs rm
$ bin/bsadmin create_index -x
$ bin/bsadmin create_index -c
$ bin/start_servers

Additionally run to fix affected previews:

$ cd <bscw-runtime-path>
$ bin/bsadmin preview create -ff

When upgrading from BSCW 5.1.3 or lower

If you are using the BSCW “lucene” indexer (package PyLucIndex), a new sort order “by start” is enabled which requires to rebuild the index if users should be able to sort search results by this criteria. See section Index creation and update for a description how to create a new index.

When upgrading from BSCW 5.0.10 or lower

To support the new BSCW 5.1 preview feature additional converter software must be installed, please see section Software for BSCW Preview for details. To disable BSCW preview feature add a CREATE_PREVIEWS = False line to the instance configuration file <bscw-runtime-path>/conf/config.py.

The default path for authenticated access has been changed from /bscw/ to /sec/. The new /sec/ path is only applied for new installations, while upgraded instance keep the old path.

The ldap package configuration file <bscw-runtime-dir>/conf/ldap/config_ldap.py was (automatically) renamed to <bscw-runtime-dir>/conf/ldap/config.py during the upgrade.

The local instance package layout in <bscw-runtime-path>/bsext has been changed. If you created a local instance package please contact support@orbiteam.de before upgrading.

Python 2.6 support has been ended.

When upgrading from BSCW 5.0.7 or lower

A security vulnerability has been discovered, which may disclose the name of objects stored in BSCW. Thanks to RedTeam Pentesting (https://www.redteam-pentesting.de/) for identifying this problem. See CVE-2014-2301 for details. Please upgrade all BSCW instances to at least version 5.0.8.

When upgrading from BSCW 5.0.6 or lower

Support for the Apache HTTP server version 2.4 has been added.

When upgrading from BSCW 5.0.4 or lower

The BSCW ldap package has been updated to map the BSCW user meta data to LDAP attributes. If you use the BSCW ldap package, please adapt your configuration file located in <$HOME>/srv/<bscw-runtime-dir>/conf/ldap/config_ldap.py according to the changes of the new default configuration file template <$HOME>/lib/bscw-7.5.4-<rev>-py3*/bscw/conf/ldap/config.py.

Note

The update_bscw directive has been converted from a tuple to a dictionary

When upgrading from BSCW 4.5.9 or lower

When upgrading to BSCW 5.0 the file system layout is automatically transformed to the new BSCW 5 layout (see installation section for details).

Note

The upgrade procedure checks all existing packages and disables outdated or non-working packages. The resulting enabled packages are sorted alphabetically into the PACKAGES list in the instance configuration file <bscw-runtime-path>/conf/config.py. If you defined an own package (e.g. to adapt the default role configuration) be aware the package might become disabled after an upgrade. If in doubt please ask support@orbiteam.de for advice on how to upgrade your customizations.

Due to the new BSCW 5 layout:

  • Please update your Apache HTTP server configuration. Change the VirtualHost container definition according to the “site” configuration template <bscw-runtime-path>/conf/apache{2,24}/site.conf, see Apache HTTP Server Configuration for Unix.

  • The former <bscw-runtime-path>/apache.conf file was renamed to <bscw-runtime-path>/conf/apache{2,24}/bscw.conf

  • Existing entries for the cron daemon (Unix) have to be adapted to the new location of the bsadmin command line script. Most likely you have to exchange <bscw-runtime-path>/bsadmin by <bscw-runtime-path>/bin/bsadmin. If you configured folder mail delivery on Unix the path to the local mail delivery agent in /etc/aliases or .forward has to be adapted, too, e.g. replace <bscw-runtime-path>/cgi/bscw.cgi by <bscw-runtime-path>/var/www/bscw.cgi

Important

During the upgrade process to BSCW 5.0 database conversion(s) are necessary. A single database conversion requires beside the conversion process two garbage collection runs; so estimate a downtime of 3 - 4 times the duration of a single garbage collection run. Especially big BSCW database servers with more than 10.000 users should consider this.

For new BSCW instances the default authentication method has been changed to cookie authentication (since BSCW 4.5). It is recommended to manually change the authentication method for existing BSCW instances to cookie authentication within the instance configuration file <bscw-runtime-path>/conf/config.py using the COOKIE_AUTHENTICATION directive (see web/proxy server settings of chapter 5 for details). After altering the authentication method bsadmin conf_apache -n, bsadmin index_page must be run for (re)configuration of the Apache HTTP server and the index page.

The mobile package requires cookie authentication as authentication method.

If you are using the BSCW “lucene” indexer (package PyLucIndex), an upgrade of pylucene to version 3.6.2 is required before running the BSCW upgrade procedure. Remind to rebuild the “lucene” index after the upgrade.

If the ldap package is enabled, the old configuration from config_ldap.py must be inserted manually in the new configuration file <bscw-runtime-path>/conf/ldap/config_ldap.py after upgrading.

All moderated public workspaces are reset to non-moderated. To restore the previous moderated state run bsadmin dbcheck repair -f m

Note

The XML-RPC and JSON-RPC API has been extended to require additional authentication information per request if the user-agent is not whitelisted. This prevents potentially injected malicious javascript code in web browsers to utilize the BSCW API. To whitelist your RPC-client user-agent you may add an entry to <bscw-runtime-path>/conf/config_clientmap.py for trusted_json_rpc_client resp. trusted_xml_rpc_client.

Important

You may never add an entry for any available web browser!

Python 2.5 support has been ended.

When upgrading from BSCW 4.4.6 or lower

The converter tool configuration file <bscw-runtime-path>/conf/config_convert.py is automatically generated by using bsadmin update_defaults -s. This script will search the local system for archiver, encoder or converter commands.

See also

Section 4.7 conf/config_convert.py

The Flow has been replaced by the Tasks package and all Flow objects will be converted to new Project/Phase objects. During the conversion the Process folders role mapping to restrict inherited roles from the surrounding Project folder was reset. Thus it might be possible for other members of the project to change data in the Process folders after the conversion.

When upgrading on a Linux-based OS you must make sure that a working compiler (GCC/CC) is installed (Due to limitations of set-group-id execution for scripts on Linux the compilation of the CGI binary wrapper became mandatory).

Whenever the SERVER_ROOT is changed in the instance configuration file <bscw-runtime-path>/conf/config.py you must call bsadmin update_helper in order to update the jnlp deployment files with the correct code base URL. Otherwise users may not be able to launch or install the BSCW Desktop application anymore.

Python 2.4 support has been ended in BSCW 4.4.6.

When upgrading from BSCW 4.4.5 or lower

Due to a (fixed) bug in the file upload process obsolete files may be still in the data/Files area. To remove this superfluous files, please perform the following command (on the server console) after having upgraded:

$ cd <bscw-runtime-path>
$ bin/bsadmin fsck -r

When upgrading from BSCW 4.4.4 or lower

The POST_AUTHENTICATION directive in the instance configuration file <bscw-runtime-path>/conf/config.py was renamed in POST_AUTH, which is now enabled by default.

When upgrading from BSCW 4.3.4 or lower

Administrator users explicitly need to log in a second time with their password at [Options ‣ Admin] to gain BSCW administrator rights. Without this additional administrator authentication no administrative rights are applied to their account. After successful login to the Admin page press [OK] to keep the administrator rights for your current session or [Cancel] to drop the administrator rights again. The administrator status is indicated by a Admin label at top of the BSCW user interface.

The syntax of the meta data configuration <bscw-runtime-path>/conf/config_metadata.py has been changed. While unmodified meta data definitions are automatically converted to the new syntax, custom meta data definitions will be disabled and need to be converted manually.

The syntax of the action configuration <bscw-runtime-path>/conf/config_actions.py has been changed. In particular the syntax of the Action class was altered. If the Action(...) definitions of your BSCW instance were changed, these changes must be adapted manually to the new format.

Users can now in addition to their user name log in with one of their allocated email addresses and their password. The ldap has been adapted to support automatic registration for email addresses.

Python 2.3 support has been ended in BSCW 4.3.4

When upgrading from BSCW 4.3.1 or lower

BSCW 4.3.2 provides a new module for maintaining BSCW database object tables in an external Berkeley DB DBMOD_TAB = 'bsddb4'. If you used DBMOD_TAB = 'bsddb3' in versions before BSCW 4.3.2 upgrade to this new module (by setting DBMOD_TAB = 'bsddb4' in the main configuration file <bscw-runtime-path>/conf/config.py). This configuration can also be used for upgrading from earlier BSCW releases.

When upgrading from BSCW 4.2.3 or lower

The SERV_UNO_ROOT directive has been deleted. BSCW services like the User Notification Services (UNO) or the alarm service expect now an additional (virtual) HTTP service running on localhost:<HTTP_LOCAL_PORT> (default: HTTP_LOCAL_PORT = 80).

Note

If you are running several BSCW instances in different virtual hosts you must configure for each BSCW instance a different HTTP_LOCAL_PORT number and you must extend the VirtualHost directives by these local IP addresses/port pairs.

The SERVER_ADMINS_IP directive no longer restricts the User Notification Services (UNO). You should remove entries from SERVER_ADMINS_IP which were made in BSCW 4.2 for SERV_UNO_ROOT resp. SERVER_ROOT.

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 behavior 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 utilized resources of all contained objects of a workspace to the owner (and not any longer to the different object creators)

    Attention

    After the upgrade 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 commits changes to the database after each user.

  • The action delete changes the owner of an object: owner becomes the user who deleted the object (the object inherits the owner of the ambient folder (who is in this case the owner of the trash)).

    Attention

    caused by this owner change the action destroy always destroys objects contained in the trash. The behavior 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 Services (UNO) which replaces the workspace activity report and the awareness service of previous BSCW versions. In order not to interfere with the new user notification service, the workspace activity report configuration must be disabled by removing the crontab (Unix) entry for bsadmin notify -a. Additionally remove the entry for AWSERV (bs_servaw) from the SERVERS list in the old instance configuration file <bscw-runtime-path>/src/config.py before upgrading. After upgrading you might add an entry for bs_servuno as described in the comments.

When upgrading from BSCW 4.0.4 or lower

The BSCW license server URI has been changed, be sure in <bscw-runtime-path>/conf/config.py the BSCW_LICENSE variable is set to:

BSCW_LICENSE = 'http://bscw.orbiteam.de/pub/'           (upgrade 3.x)
BSCW_LICENSE = 'https://bscw.orbiteam.de/pub/bscw.cgi/' (upgrade 4.x)

Important

Starting with BSCW 4.0.6 a new license mechanism was introduced. The new mechanism no longer binds the license to the BSCW servers’ IP address and installation path. It is name based, which means you have to define in <bscw-runtime-path>/conf/config.py the SERVER_ROOT variable before applying for a license.

See also

Section 3.4.2 BSCW instance configuration for Unix

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 adapt your configuration to the new layout as given in <bscw-runtime-path>/apache24/bscw.conf.

See also

Section 3.4.1 Apache HTTP Server Configuration for Unix

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 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) any more. 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 also

Chapter 8 BSCW license

Note

New packages are not automatically enabled after upgrading. You have to add the package names to the PACKAGES list in the server settings of the [Options ‣ Admin]-page or the file <bscw-runtime-path>/conf/config.py. Some of the packages also need installation of extra software and configuration.

When upgrading from BSCW 2.2 or lower

Execute the following commands in your existing BSCW2 instance directory <bscw-runtime-path> before installing the new version:

$ cd <bscw-runtime-path>
$ 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 upgrade and reconfiguration of your HTTP server as described in chapter 3 Installation procedure for Unix.

Note

You may not replace the upgraded BSCW server instance configuration file <bscw-runtime-path>/conf/config.py by a config.py file of a previous BSCW version! Instead, the upgraded BSCW server instance configuration file must be edited manually.

Since the Apache HTTP server configuration <bscw-runtime-path>/apache2/bscw.conf is automatically generated all manual changes will be lost after an upgrade.

2.4.1. Upgrading on Unix

To upgrade an existing BSCW instance on Unix, first make sure that one of the supported Python 3 versions (3.8, 3.9, 3.10, 3.11) is available on the host of the BSCW instance.

The installation program of the BSCW software must be run as superuser (root)

$ su -
# tar xf bscw-7.5.4-<rev>-py3*.tar.gz
# cd bscw-7.5.4-<rev>-py3*
# ./install.sh

The installation procedure looks for the BSCW system user bscw (resp. requests the user name of your BSCW user account) and locates all BSCW instances.

If you do not want to run the install.sh script as superuser or you encounter further problems, you may install BSCW completely manual as follows:

  • login as bscw user

    # su - bscw
$ id bscw
uid=1234(bscw) gid=1234(bscw) groups=1234(bscw)

  • create a $HOME/lib directory in the bscw users’ home directory

    $ cd $HOME
$ mkdir lib

  • download the BSCW distribution into a temporary directory, extract the archive and extract the BSCW distribution tar file into $HOME/lib, e.g.

    $ cd /tmp
$ tar xf bscw-7.5.4-<rev>-py3*.tar.gz
$ cd $HOME/lib
$ tar xf /tmp/bscw-7.5.4-<rev>-py3*/bscw-7.5.4-<rev>-py3*.tar

  • run the installation procedure setup.py <bscw-runtime-path> and follow the instructions

    $ cd $HOME/lib/bscw-7.5.4-<rev>-py3*
$ python3 ./bin/setup.py <bscw-runtime-path>

In particular the installation procedure performs the following steps to upgrade a BSCW instance

# ./install.sh
Enter BSCW system user name: [bscw]
Enter BSCW base directory: [/opt/bscw]
Extracting BSCW 7.5.4 distribution in /opt/bscw/lib
Choose one of the following options:
 ( 0) update BSCW 4.5.9 [/opt/bscw/server]
 ( 1) update BSCW 5.2.6 [/opt/bscw/srv/bscw.domain.org]
 ( 2) update other BSCW instance
 ( 3) create new BSCW instance
Enter a number (0-2): 1

target '/opt/bscw/srv/bscw.domain.org' exists - checking...
stop pid=22823
2022-08-28 09:28:12 BSCW indexer (PyLucene 3.6.2) PID 22835 terminated
2022-08-28 09:28:12 Stopped bscw.adm.bs_servdb
2022-08-28 09:28:12 Stopped bscw.adm.bs_servuno
2022-08-28 09:28:12 Stopped bscw.adm.bs_servaccess
2022-08-28 09:28:12 Stopped bscw.adm.bs_servalarm
2022-08-28 09:28:12 Stopped bscw.cli.http.op_http: not running
Loading EXTENSIONS from conf-20220828-0928
old msg -> conf/msg (copied)
old config_run.py -> conf/config_run.py (copied)
old ldap/config.py -> conf/ldap/config.py (copied)
New package airdesktop enabled
config.py updated
'/opt/bscw/srv/bscw.domain.de/conf/__init__.py' updated
old apache24 -> conf/apache24 (copied)
Import core modules ...
Link 'libexec' already exists - updating link...
Link destination '/opt/bscw/lib/bscw-7.5.4-<rev>-py3*/extensions' does not exist
Found "Programs" (located):
  [...]
config_convert.py created
bsadmin update_defaults -v
bsadmin manage_servers -u
2022-08-28 09:28:14 bsadmin chkconfig -check-access
2022-08-28 09:28:14 access checks...
cc -o var/run/run_bscw var/run/run_bscw.c
2022-08-28 09:28:14 Actual license: OK
2022-08-28 09:28:14 bsadmin start
2022-08-28 09:28:15 Database version >= 2.1
2022-08-28 09:28:15 bsadmin bscw.adm.bs_convert30 -t
2022-08-28 09:28:15 Database version >= 3.0
2022-08-28 09:28:15 bsadmin bscw.adm.bs_convert31 -t
2022-08-28 09:28:15 Database version >= 3.1
2022-08-28 09:28:15 bsadmin bscw.adm.bs_convert33 -t
2022-08-28 09:28:15 Database version >= 3.3
2022-08-28 09:28:15 bsadmin bscw.adm.bs_convert40 -t
2022-08-28 09:28:15 Database version >= 4.0
2022-08-28 09:28:15 bsadmin bscw.adm.bs_convert45 -t
2022-08-28 09:28:15 Database version >= 4.5
2022-08-28 09:28:15 bsadmin bscw.adm.bs_convert50 -t
2022-08-28 09:28:15 Database version >= 5.0
2022-08-28 09:28:15 bsadmin bscw.adm.bs_convert51 -t
2022-08-28 09:28:15 Database version >= 7.0
2022-08-28 09:28:15 bsadmin bscw.adm.bs_convert70 -t
2022-08-28 09:28:15 Database version >= 7.1
2022-08-28 09:28:15 bsadmin bscw.adm.bs_convert71 -t
2022-08-28 09:28:15 Database version >= 7.5
2022-08-28 09:28:15 bsadmin bscw.adm.bs_convert72 -t
2022-08-28 09:28:15 Converting to Version 7.5 ...
2022-08-28 09:28:15 bsadmin garbage -map bscw.adm.bs_classtable30
2022-08-28 09:28:16 GC actual license: OK.
2022-08-28 09:28:16 GC init
2022-08-28 09:28:16 GC init tables
2022-08-28 09:28:16 GC users: 1, roots: 4, old relatives: 0
2022-08-28 09:28:16 GC offsets: 113
                    GC start collection: size: 20792
2022-08-28 09:28:16 GC check relatives
2022-08-28 09:28:16 GC 1 relatives appended (0 on hold)
2022-08-28 09:28:16 GC check relatives
2022-08-28 09:28:16 GC 0 relatives deleted
                    GC done, size: 20821, objects: 114, roots: 4.
2022-08-28 09:28:16 GC Store: var/data/StoreB size: 20821, lastid: 130
2022-08-28 09:28:16 GC Backup: var/data/Backup
2022-08-28 09:28:16 bsadmin bscw.adm.bs_convert72 -x
2022-08-28 09:28:16 start conversion commit:True
Scan 1136729 objects for conversion
all done
2022-08-28 09:28:16 exit conversion commit:True converted:True
2022-08-28 09:28:16 Database version == 7.5
2022-08-28 09:28:16 bsadmin start
2022-08-28 09:28:16 bsadmin bscw.adm.bs_fix_anonymous
2022-08-28 09:28:16 bsadmin http restart
restart pid=13582
2022-08-28 09:28:16 VERSION:  BSCW 7.5.4
                    Released: 20230203-1041-c217ad7
bsadmin convert -check-access
Configure 'gzip' compression ...
Configure 'static' resources '/opt/bscw/lib/bscw-7.5.4-<rev>-py3*/bscw/resources'...
          'local' resources 'var/www/20230203-1041-c217ad7'
 (Long time future expire dates)
Configure public prefix '/pub/' (Apache 24)...
 (No authentication)
Configure secure prefix '/bscw/' (Apache 24) ...
 (HTTP_AUTHORISATION passed to BSCW)
 (Cookie authentication enabled)

Creating Apache HTTP server configuration files in
/opt/bscw/srv/bscw.domain.de/conf/apache24
   mod.conf ... module configuration file
  site.conf ... virtual host site configuration file
  bscw.conf ... BSCW configuration file
bsadmin conf_apache
bsadmin index_page

BSCW server up and running in '/opt/bscw/srv/bscw.domain.de'

BSCW instance updated: '/opt/bscw/srv/bscw.domain.de'
you may need to restart your web-server

Installation succeeded. For next steps please check
/opt/bscw/lib/bscw-7.5.4-<rev>-py3*/README.txt

Since Linux environments do not execute forked processes
set-group-id it is advisable to recursively change the owner the
preview cache and ./var/data files and directories to the
web server user.
Fix file owner/modes for Apache HTTP daemon user? [Y/n]

By default, the installation procedure looks in the home directory of the given BSCW user $HOME/ and $HOME/srv/ to locate a BSCW instance. If you installed your BSCW instance in a non-standard location, the BSCW installation program may not be able to locate the BSCW instance directory. In this case you have two options to upgrade from a previous version to BSCW 7.5.4:

  1. Provide the path to your BSCW instance to the BSCW installer

  2. Adopt the new BSCW layout and move your BSCW instance (recommended)

How to proceed for each option:

  1. Provide the path to your BSCW instance to the BSCW installer

    If you want to preserve the old non-standard location for your BSCW instance, it is possible to specify the path to your BSCW instance by choosing the option update other BSCW instance:

    # ./install.sh

Enter BSCW system user name: [bscw]

Enter BSCW base directory: [/opt/bscw]

Extracting BSCW |release| distribution in '/opt/bscw/lib'

Choose one of the following options:
 ( 0) update other BSCW instance
 ( 1) create new BSCW instance
Enter a number (0-1): 0

Enter path to BSCW instance: /usr/local/bscw/server
target '/usr/local/bscw/server' exists - checking...
...

    Alternatively it is possible to specify the path to your BSCW instance as argument of the BSCW installer program:

    # ./install.sh /usr/local/bscw/server

target '/usr/local/bscw/server' exists - checking...
...

    This will upgrade your BSCW instance to BSCW 7.5.4 “in-place” and keep the BSCW instance in the old directory.

  2. Adopt the new BSCW layout and move your BSCW instance (recommended)

    It is recommended to move the old BSCW instance first to the new standard location ./srv/<hostname> in the BSCW users’ home directory (e.g. /opt/bscw/srv/<hostname>). First stop the BSCW server and then move it:

    $ su -
# cd /usr/local/bscw
# ./server/start_servers -k

# BSCW_HOME=`su - bscw -c 'echo $HOME'` # e.g. BSCW_HOME=/opt/bscw

# mkdir -p                      $BSCW_HOME/srv/bscw.domain.org
# chown bscw:bscw               $BSCW_HOME/srv/bscw.domain.org
# rsync -vaH –del ./server/*    $BSCW_HOME/srv/bscw.domain.org
...

    Next run the BSCW installer (as root) - with no argument it should find the instance and offer to upgrade it:

    # ./install.sh
...
Choose one of the following options:
 ( 0) update BSCW 5.2.6 [/opt/bscw/srv/bscw.domain.org]
 ( 1) update other BSCW instance
 ( 2) create new BSCW instance
Enter a number (0-2): 0
...

    The BSCW installer will update your BSCW instance to BSCW 7.5.4. You finally need to adjust the HTTP server configuration. See configuration section above.