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 - or a server host running Microsoft Windows 10, Server 2016/2019.

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 >3,2 GHz Intel Core/Xeon or AMD EPYC/Ryzen with at least 4 cores, 8 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 http://www.python.org/). Therefore, besides the BSCW software, the installation of the BSCW server requires

a Web Server
a Python 2.7 interpreter
(optional) extensions for Python (pylucene, python-ldap)
(optional) converter software for the BSCW preview feature, see sections 3.3 Software for BSCW Preview (Unix) or 4.3 Software for BSCW Preview (Windows) for details

The BSCW server can be installed on a CGI compliant Web server, e.g. the Apache HTTP server or the Microsoft’s Internet Information Server (IIS) (we recommend the Apache HTTP server version 2.4). The Python interpreter is freely available on the Python website (http://www.python.org/). We currently support version 2.7 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.

The installation process is different between Unix systems and Windows 10 or Server 2016/2019. Therefore, the installation process for Unix and Windows is described separately in sections Installation procedure for Unix and Installation procedure for Windows of chapters 3 and 4, respectively. You need to read only one of the two sections, depending on your platform.

The configuration process to a large extent is identical for Unix and Windows. Whenever a difference is necessary, this is described at the respective places in this manual.

Note

Please also consult chapter 10 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:

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.
Enabled web services

BSCW offers a range of services via different web service protocols: XML-RPC, JSON, SOAP. Basically most of the actions available on the user interface (like “add folder”) are accessible via a web service API. Of course access to API is restricted via access control as in the regular user interface (i.e., authentication and BSCW internal roles and rights are respected). The availability of the web service API on different user levels can be configured by editing the ACCEPT_WEBSERVICES directive in the instance configuration file <bscw-runtime-path>/conf/config.py.

See also

BSCW database server settings of chapter 5 for the description of the ACCEPT_WEBSERVICES directive page for details.
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 7.5 Public space deactivation.
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-5.2.6-<rev>-py27/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 5.2.6¶

If you are installing BSCW for the first time please refer to the installation sections (Installation procedure for Unix, Installation procedure for Windows). 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 to version 2.7 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.5

> bin\bsadmin manage_servers -l
C:\BSCW\srv\bscw.domain.org:     BSCW 5.2.5

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 or Upgrading on Windows to consider the following advices when upgrading:

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.

This is probably the last BSCW 5.2 version. BSCW 5.2 will be replaced by the successor version 5.3, which is a port of BSCW 5 to Python 3.

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.

BSCW is largely compliant with the Barrier-Free Information Technology Ordinance (BITV 2.0). By default, some requirements of the BITV are not met. This can be changed by setting BITV_STANDARD to True.

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 resp. Software for BSCW Preview Windows

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) and for Windows systems section 4.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 (3.3 (Unix) or 4.3 (Windows)) 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.

Configuration setting for the rss package have to be moved from instance configuration file <bscw-runtime-path>/conf/config.py to the package configuration file <bscw-runtime-path>/conf/rss/config.py.

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-5.2.6-<rev>-py27/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 resp. Apache HTTP Server Configuration for Windows.

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) resp. Task Scheduler (Windows) 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 5.8 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.

BSCW Windows instances require at least Python for Windows Extensions version 2.14. Please upgrade older pywin32 versions before running the BSCW installer.

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:

EDU licensees may only run the command bsadmin quota fix.

PRO licensees may run alternatively the command bsadmin quota report -vL, which 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 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) or the task scheduler (Windows) 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 or section 4.5.1 BSCW Server Root Definition 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 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 or section 4.5.2 Apache HTTP Server Configuration or section 4.5.3 IIS Configuration for Windows

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 9 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 or chapter 4 Installation procedure for Windows.

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¶

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

$ su -
# tar xf bscw-5.2.6-<rev>-py27.tar.gz
# cd bscw-5.2.6-<rev>-py27
# ./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-5.2.6-<rev>-py27.tar.gz
$ cd $HOME/lib
$ tar xf /tmp/bscw-5.2.6-<rev>-py27/bscw-5.2.6-<rev>-py27.tar
```
run the installation procedure setup.py <bscw-runtime-path> and follow the instructions
```
$ cd $HOME/lib/bscw-5.2.6-<rev>-py27
$ python2 ./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 5.2.6 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.5 [/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...
2020-08-28 09:28:12 bscw.adm.bs_servdb: not running
2020-08-28 09:28:12 bscw.adm.bs_servalarm: not running
Loading EXTENSIONS from conf-20200828-0928
old msg -> conf/msg (copied)
old config_run.py -> conf/config_run.py (copied)
old config_convert.py -> conf/config_convert.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
config_run.pyc created
old apache2 -> conf/apache2 (copied)
old apache24 -> conf/apache24 (copied)
Import core modules ...
Link 'libexec' already exists - updating link...
Link destination '/opt/bscw/lib/bscw-5.2.6-<rev>-py27/extensions' does not exist
config_convert.py updated
bsadmin update_defaults
bsadmin manage_servers -u
2020-08-28 09:28:14 bsadmin chkconfig -check-access
2020-08-28 09:28:14 access checks...
cc -o var/run/run_bscw var/run/run_bscw.c
2020-08-28 09:28:14 Actual license: OK
2020-08-28 09:28:14 bsadmin start
2020-08-28 09:28:15 Database version >= 2.1
2020-08-28 09:28:15 bsadmin bscw.adm.bs_convert30 -t
2020-08-28 09:28:15 Database version >= 3.0
2020-08-28 09:28:15 bsadmin bscw.adm.bs_convert31 -t
2020-08-28 09:28:15 Database version >= 3.1
2020-08-28 09:28:15 bsadmin bscw.adm.bs_convert33 -t
2020-08-28 09:28:15 Database version >= 3.3
2020-08-28 09:28:15 bsadmin bscw.adm.bs_convert40 -t
2020-08-28 09:28:15 Database version >= 4.0
2020-08-28 09:28:15 bsadmin bscw.adm.bs_convert45 -t
2020-08-28 09:28:15 Database version >= 4.5
2020-08-28 09:28:15 bsadmin bscw.adm.bs_convert50 -t
2020-08-28 09:28:15 Database version >= 5.0
2020-08-28 09:28:15 bsadmin bscw.adm.bs_convert51 -t
2020-08-28 09:28:15 Converting to Version 5.2 ...
2020-08-28 09:28:15 bsadmin garbage -map bscw.adm.bs_classtable30
2020-08-28 09:28:16 GC actual license: OK.
2020-08-28 09:28:16 GC init
2020-08-28 09:28:16 GC init tables
2020-08-28 09:28:16 GC users: 1, roots: 4, old relatives: 0
2020-08-28 09:28:16 GC offsets: 113
                    GC start collection: size: 20792
2020-08-28 09:28:16 GC check relatives
2020-08-28 09:28:16 GC 1 relatives appended (0 on hold)
2020-08-28 09:28:16 GC check relatives
2020-08-28 09:28:16 GC 0 relatives deleted
                    GC done, size: 20821, objects: 114, roots: 4.
2020-08-28 09:28:16 GC Store: var/data/StoreB size: 20821, lastid: 130
2020-08-28 09:28:16 GC Backup: var/data/Backup
2020-08-28 09:28:16 bsadmin bscw.adm.bs_convert51 -x
2020-08-28 09:28:16 start conversion commit:True
Scan 1136729 objects for conversion
01% done
...
all done
2020-08-28 09:28:16 exit conversion commit:True converted:True
2020-08-28 09:28:16 Database version == 5.2
2020-08-28 09:28:16 bsadmin start
2020-08-28 09:28:16 bsadmin bscw.adm.bs_fix_anonymous
2020-08-28 09:28:16 VERSION:  BSCW 5.2.6
                    Released: 20221006-1545-2ba118f
bsadmin convert
Configure 'gzip' compression ...
Configure 'static' resources '/opt/bscw/lib/bscw-5.2.6-<rev>-py27/bscw/resources'...
          'local' resources 'var/www/20221006-1545-2ba118f'
 (Long time future expire dates)
Configure secure prefix '/bscw/' (Apache 2) ...
 (HTTP_AUTHORISATION passed to BSCW)
 (Cookie authentication enabled)
Configure public prefix '/pub/' (Apache 2)...
 (No authentication)
Configure secure prefix '/bscw/' (Apache 24) ...
 (HTTP_AUTHORISATION passed to BSCW)
 (Cookie authentication enabled)
Configure public prefix '/pub/' (Apache 24)...
 (No authentication)

Creating Apache HTTP server configuration files in
/opt/bscw/srv/bscw.domain.de/conf/apache{2,24}
   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-5.2.6-<rev>-py27/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 5.2.6:

Provide the path to your BSCW instance to the BSCW installer
Adopt the new BSCW layout and move your BSCW instance (recommended)

How to proceed for each option:

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 5.2.6 “in-place” and keep the BSCW instance in the old directory.

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.5 [/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 5.2.6. You finally need to adjust the HTTP server configuration. See configuration section above.

2.4.2. Upgrading on Windows¶

Before upgrading a BSCW instance ensure to install the Python for Windows Extensions (pywin32) at least with Build 219. To upgrade an existing BSCW instance on Windows start the BSCW setup procedure by double-clicking

bscw-5.2.6-<rev>-py27.exe

This will (re-)install the BSCW 5.2.6 distribution files in the given location. Next start the BSCW instance setup program by keeping the option Install a server instance now selected and pressing [Finish]. To perform an upgrade, select the BSCW instance to be updated, e.g.:

[upgrade BSCW 4.5.9 [c:\bscw\server]]
[upgrade BSCW 5.2.5 [c:\bscw\srv\bscw.domain.org]]
install new BSCW instance

and click [Continue]. A console window is opened and the selected BSCW instance runtime directory is updated.

Table of Contents

Previous topic

Next topic

2. Installation of the BSCW server¶

2.1. General Requirements¶

2.2. Security considerations¶

2.3. EU - General Data Protection Regulation¶

2.4. Upgrading to BSCW 5.2.6¶

2.4.1. Upgrading on Unix¶

2.4.2. Upgrading on Windows¶