9. Frequently Asked Questions (FAQ)¶

9.1. BSCW Server Usage¶

9.1.1. What do I need to use BSCW?¶

You need a personal email address to register.
You need need a Web browser to access shared workspaces and to download documents to your local computer. Most Web browsers (e.g. Firefox, Chrome, Safari and Edge) are compatible. We recommend using latest versions of Firefox.

On most computers everything is already available. You need no special software installation to start with BSCW.

Keywords: Prerequisites, usage of BSCW

9.1.2. Do I need a special application for uploading documents?¶

No, you only need your browser application. Today’s browsers include support for uploading based on a standard protocol and BSCW users may upload documents using these browsers with no problems.

Keywords: upload documents

9.1.3. How is BSCW intended to be used¶

BSCW is a groupware application. Users share workspace folders which contain objects. These objects can be files, discussions, notes, calenders etc.

To start with BSCW a user has to create a workspace. Then he invites users to this workspace. These users can be already registered or unregistered. Invitation is possible with the users user name if he already has one or with the new users email address.
After invitation the shared workspace folder appears in the home folder of the invited user. The invited user may now access the shared workspace.
If a user leaves a group he may simply be removed from the list of workspace members.

It’s also possible to define special access rights for invited members by using the built-in role based access control system. Please read the documentation for more details.

Keywords: Usage of BSCW

9.1.4. I cannot log in. The server rejects me - what shall I do?¶

Please mind that the BSCW server distinguishes between uppercase and lowercase characters in username and password.

If you forget your password, you can’t change your password in the normal way. For this emergency case, BSCW provides a specific procedure to assign a new password without having to provide the old one:

Open the URL https://<your-server>/pub/bscw.cgi?op=chpwd (e.g. https://public.bscw.de/pub/bscw.cgi?op=chpwd on the public BSCW server)
Fill in the form with your primary email address
An email with further instructions to reset your password will be sent to you - follow instructions in the email.

Keywords: login failed, forgotten password, forgotten user name

9.1.5. How do I change my password?¶

You may change your password using the user menu [Change Password] item in the right upper corner of the interface.

Keywords: password, change password

9.1.6. How do I connect to BSCW using WebDAV?¶

WebDAV (Web-based Distributed Authoring and Versioning, see www.webdav.org) is a standard protocol which allows users to access files on remote web servers. BSCW implements WebDAV so that it is possible to browse, upload and download files on a BSCW server using a WebDAV compliant client tool.

WebDAV protocol support is integrated in most operating systems such as MacOS, Windows and Linux (using GNOME, for example). Alternatively, special WebDAV client applications may be used which are available for different platforms and at different licensing models (for example: cadaver, DAV Explorer).

Connecting to a WebDAV enabled server typically only requires provision of the network URL and user credentials (user name and password), however, the process may vary depending on the WebDAV application used. In the following we shortly describe how to connect to a WebDAV enabled BSCW server using Windows 11.

Note

Not every BSCW server is WebDAV enabled. This depends on the BSCW version and the server configuration. If in doubt ask your BSCW administrator for help.

9.1.6.1. How to connect to BSCW using WebDAV on Windows 11¶

In order to connect to the BSCW server using WebDAV, it is recommended to open the “Computer” (icon on your desktop) then right-click (in an open space of the Window) and to select “Add a Network Location” from the context menu. In the “Add Network Location Wizard” click [Next]., choose a “custom network location” and enter the URL of the BSCW server when prompted for the “location of the website”. Enter the full BSCW server URL (including /sec/bscw.cgi resp. /bscw/bscw.cgi) in the “Internet or network address field”.

For example, enter https://bscw.domain.org/sec/bscw.cgi (resp. https://bscw.domain.org/sec/bscw.cgi) and click [Next]. You will then be prompted for your BSCW user name and password. If everything works fine you will finally be prompted for a name for this location - enter a label of your choosing (e.g. “My BSCW Server”). A new item in your “Computer” with that name should then appear ” (note that this operation may take some time for the first time). The item provides access to the BSCW server: your home folder (‘:username’) is accessible via the alias folder ‘home’. You may now browse your workspaces using the Windows File Explorer, and upload or download files (using copy & paste or drag & drop).

Note

In order to reuse WebDAV resources stored on Windows 11 you have to enable the “WebClient service” by setting the service Startup type to “Automatic”.

9.1.6.2. Troubleshooting¶

In case the above described method does not work (e.g. password dialog keeps popping up) the following tips have proven to help in most cases on Windows:

Try to connect using https i.e. enter the full URL https://bscw.domain.org/sec/bscw.cgi/ (resp. https://bscw.domain.org/bscw/bscw.cgi/)
If your server doesn’t support HTTPS, ask your BSCW administrator to enable HTTPS on the server. If that is not possible follow the hints given by Microsoft on how to enable basic authentication for WebDAV on the client computer (see below).
If the password dialog pops up again and contains a hostname in front of your username (e.g. “serversmith”), correct the username (i.e. remove “server”), enter your password and click [OK] (this step may need to be performed several times when connecting for the first time).
If establishing a network connection to your BSCW server is still not possible, try to add the network location and enter the ‘share’ URL: \\bscw.domain.org\sec\bscw.cgi (resp. \\bscw.domain.org\bscw\bscw.cgi)
Make sure you have installed all recent updates and service packs.
Make sure your BSCW server is running the most recent version of the BSCW software. If in doubt ask your BSCW administrator for help.

9.1.6.3. Hints for Windows 11¶

On Windows 11 you may not connect to your BSCW server as a network drive using WebDAV if the server does not support SSL. You may want to ask your BSCW administrator to enable HTTPS on the server. If that is not possible, you may want to follow the hints given by Microsoft on how to enable basic authentication for WebDAV on the client computer:

Click Start , type regedit in the Start Search box, and then click regedit in the Programs list.

Locate and then click the following registry key:

HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\WebClient\Parameters

On the Edit menu, point to New, and then click DWORD Value.
Type BasicAuthLevel, and then press Enter.
On the Edit menu, click Modify. In the Value data box, type 2, and then click OK.
Close the registry editor. Finally, you should restart you computer.

Note

For security purposes, Windows disables basic authentication in the Web Distributed Authoring and Versioning (WebDAV) Redirector. Therefore either use of HTTPS (SSL connection) is required or a special configuration (on the client) has to be done as described in the MS Knowledgebase: https://support.microsoft.com/kb/841215/en-us

9.1.6.4. Hints for BSCW administrators¶

In case your users encounter problems with WebDAV connections, the following tips have proven to help in most cases:

Make sure you’re BSCW server is running the most recent version of the BSCW software. (Check the website www.bscw.de for updates.)
You may change the authentication method BSCW uses when user credentials are passed to BSCW. The configuration variable AUTH_MODE may be set to Basic (for basic access authentication) or Digest (for digest access authentication). Basic authentication may limit WebDAV access if SSL is not enabled (see above).

Attention

Digest authentication is not possible in combination with LDAP or with email address login.
If you operate more than one BSCW-Server instance on one host, you should make sure that all BSCW-Server instances are running the same (most recent) version of the BSCW software. You must then select one of the servers in order to handle WebDAV PROPFIND - Requests for the root resource ('/'). This is achieved by setting the SCRIPTS_OTHER_ROOTS variable in the server configuration file <bscw-runtime-path>/conf/config.py (see comments there).
When changing your server configuration (i.e. <bscw-runtime-path>/conf/config.py) regarding WebDAV, make sure you update the HTTP server configuration via bsadmin conf_apache -n and do not forget to restart your Apache Web Server.

Please refer to the following table to see if the WebDAV edit feature works:

Windows

IE

Office

Protocol

BSCW >=

Edit

*

*

*

HTTP

*

no

10 64bit

Edge

Office 2016

HTTPS

7.1.0

yes

10 64bit

Edge

Office 2016

HTTPS

7.1.0

yes

enable WebClient-Service (set to “automatic”) (Windows 11)
deactivate proxy timeout for WebDAV requests

Description: https://support.microsoft.com/kb/2445570

Keywords: WebDAV

9.1.7. How do I destroy a workspace?¶

You may destroy a workspace by first removing all members of this workspace except yourself. Then the workspace can be deleted and moved into your trash. Afterward you can remove the workspace from the trash.

If you are not owner of the workspace and you remove the workspace without removing all members first, the workspace is only removed from your home folder. Other workspace members still have access to it.

If you are owner of the workspace and you remove the workspace from the trash, the system will automatically remove all members of this workspace so no one may further access it. The system will provide a warning message in this case.

Keywords: destroy workspace, remove members

9.1.8. How do I delete my account?¶

Only if enabled, it is possible to delete your own user account with [Destroy Account] in the user menu in the right upper corner of the interface. If this menu entry is missing you cannot delete your account. If you do not want to receive daily email reports any more you may simply disable this in [Preferences] [Notifications] [Active Event Services]. If you really want to be deleted please contact your local BSCW administrator.

Contact our Support team only if you are using a BSCW server that is operated by OrbiTeam. Don’t forget to provide your username and server address (URL).

Keywords: delete account

9.1.9. How do I handle a BSCW error?¶

If you encounter a BSCW error message System error you may have found a bug in the software or a problem in the system configuration. Please first contact your local BSCW server administrator.

If the problem may not be solved, please contact the Support team at support@orbiteam.de and include the following information in your report:

the URL of the BSCW server you use,
the time the error occured and the complete error message you get,
describe exactly what you did before you got this error message,
if you think more information about the computer system you are using is needed, include it.

Thank you very much for help.

Keywords: BSCW error, bug report

9.1.10. I reached the limit of my disk space - what shall I do?¶

The disk space an object occupies is subtracted from the quota of the owner of the workspace the object is in(and not to the quota of the creator of the object!). This is the reason why

your quota does not decrease when you upload files to a shared workspace you are not the owner of,
you are sometimes asked that another user has to delete files. He is the owner of the workspace you want to upload files to and his quota is exhausted.

There is a soft and a hard quota. You can exceed the soft quota temporarily for some days. After that it is not possible to upload files in the workspaces any more. You can never exceed your hard quota.

To upload files the owner of the workspace must have enough free space. Ask the owner of the workspace for help. He should delete some files. Normally there are files in the waste. To empty the garbage

please enter your [Trash]
press [Clear waste]

If this doesn’t resolve your disk space problem you may ask your system administrator to provide you with more disk space. This is not possible on the public BSCW server at https://public.bscw.de/.

Note

Disk space limiting is set per user.
Disk space accounting concerns all workspaces you are the owner of.
You can control your quota the following way:
- Open the chat view your user by clicking on your username and open the info page by clicking the white (i) overlay in the users’ icon
- On the info-page you’ll find all necessary information about used disk space and quota.
- You may check your quota limit and the amount of currently used space.

Keywords: quota, disk space limit

9.1.11. Why does MS-Word mark a document as read-only?¶

This depends on the used version of MS-Office as well as on the configuration of your BSCW server. Recent versions of BSCW allow direct editing of documents using MS-Office. Please contact your local BSCW administrator if this feature is available on your BSCW server.

In case the direct editing of documents using MS-Office is not available on your BSCW server, a Word document that is downloaded from a BSCW server and opened with the MS-Word application may be marked as Read-Only (because Word realized that this document came from a web resource and MS-Word can not save it back to this web resource). If you want to edit the document, you have to save it locally on your PC ([Save as]) and replace or revise the corresponding BSCW document on the BSCW server when you have finished editing.

Keywords: MS-Office, editing documents, Word-documents, Read-Only

9.1.12. Is there a restriction for the size of documents I upload?¶

No, there is no general restriction. If you run into problems while trying to upload large documents

Please check your local network configuration (firewall, proxy etc.) Some networks restrict the size of files that may be uploaded through the network to a remote server. Contact your local system administrator for details.
Please check your browser. Some browsers have problems with uploading large files.
You may switch to a WebDAV client

Keywords: restriction, size, upload

9.2. BSCW Server Software¶

9.2.1. How do I get the BSCW software?¶

The latest version of the software is always available for download from our download pages at https://www.bscw.de/en/social/#download

Usage of the BSCW server software is limited to a testing and evaluation period of 90 days and restricted to 200 users. After that period you have to acquire a license to continue usage. The distribution of BSCW licenses is handled by OrbiTeam Software GmbH & Co. KG, a spin-off company of FIT Fraunhofer Institute.

Schools and universities may apply for royalty free licenses for educational use only. In this case, BSCW must not be used commercially or in the context of funded projects. Any other use of the software requires the payment of a license fee.

For more information on licensing conditions and license fees, please contact our sales department at license@orbiteam.de.

Keywords: BSCW software, download, licensing

9.2.2. Can I try the BSCW software?¶

You may evaluate the BSCW software for 90 days free of charge.

For this purpose you may either use a demo server for the BSCW social or BSCW classic product provided by OrbiTeam and test the software online - or download the software and test it on your own server.

Please note that for the on-line trial all data you upload will be deleted after 90 days.

Keywords: BSCW software, online trial, evaluation

9.2.3. How do I keep up to date with BSCW developments and new releases?¶

The best way to keep up to date is to subscribe to our announcement mailing list. You may subscribe to this mailing list on the website - and of course unsubscribe at any time.

You will find the archive of this list at

Customers will also be notified about new releases automatically (i.e. they are automatically subscribed to this list).

You may also want to follow us on Twitter or Facebook for more instant updates.

Finally you may want to check our website BSCW frequently to check for news and updates.

Keywords: new releases, update, developments, announcement mailing list

9.3. BSCW Server Administration¶

9.3.1. What facilities are available for server administrators?¶

BSCW provides a HTML and a command line interface for server administration.

To be able to access the HTML administration interface with [Admin] in the user menu in the right upper corner of the interface, you must have an account on the BSCW server and your account name must appear in the SERVER_ADMINS list in the main server configuration file (<bscw-runtime-path>/conf/config.py).

Administrator users explicitly need to log in a second time with their password at [Admin] to gain BSCW administrator rights. Without this additional administrator authentication no administrative rights are applied to their account.

The administrative command line interface is accessed via the bsadmin script which is located in the BSCW server instance path bin directory <bscw-runtime-path>/bin/bsadmin. Enter bsadmin to get a list of all installed administrative modules or bsadmin <command> for instructions about the usage of a specific tool.

9.3.2. How do I delete a user from the BSCW server?¶

Open the [User administration] page of the HTML administration interface [Admin]. Find the respective user and select [Permanently destroy].

Using the command line interface bsadmin rmuser destroys a given user name.

Keywords: User administration, delete a user from server

9.3.3. How do I rename a user?¶

Open the [User administration] page of the HTML administration interface [Admin]. Find the respective user and select [Change Name].

Using the command line interface bsadmin rename renames a given user name.

Keywords: User administration, rename a user

9.3.4. How do I register a new user (i.e. without sending email)?¶

This is possible through the [New User] action of the HTML administration interface. Enter the email address and then allocate the address to a new user name with a password.

The command line interface provides the bsadmin register script, use the following syntax to register a new user:

$ bin/bsadmin register -r <email> <login_name> <password>

Keywords: User administration, register new users

9.3.5. How do I restrict the creation of workspaces?¶

Workspaces are “created” by adding members to a folder. To disallow an user the creation of new workspaces her/his role may not contain actions from the “share view” so s/he is not able to invite members. Hence to effectively deny the creation of new workspaces requires a change of the “user role”, which is by default the “Manager” role.

An BSCW administrator may enforce such a restriction in two ways:

To restrict single users edit the “user role” of or assign a new “user role” to her/his user object. The user role is inherited by the users’ top level folders (home, etc.) along the folder hierarchy:
- First open the chat view of the user:
```
https://<your server>/sec/bscw.cgi/u<username>
```
  resp.
```
https://<your server>/bscw/bscw.cgi/u<username>
```
  and then open the users’ info page by clicking the white (i) overlay in the users’ icon.
- Edit the (default) user role “Manager” and select the actions you want to restrict/allow using [Edit role]` from the Administrator actions.
- Alternatively you may assign a more restrictive role to the user with [Assign role] from the Administrator actions.
If you want to generally disallow users to create workspaces it is advisable to define a server-wide more restrictive user role, see section 6.8.2 Role definition and default roles for details.

Keywords: restrict user actions, restrict creation of new workspaces

9.3.6. How do I restrict the creation of new user accounts?¶

By default the BSCW server allows generally self-registration of email addresses and the creation of BSCW user accounts.

The MAY_REGISTER list in the main server configuration file <bscw-runtime-path>/conf/config.py restricts the ability to register new email addresses to the listed BSCW users. If the MAY_REGISTER list is not empty, only the listed users (beside BSCW administrators) are allowed to create new email addresses using the [Invite Member] action in the member menu (see also the RESTRICT_MAIL in <bscw-runtime-path>/conf/config.py for further methods to restrict registration.)

Keywords: restrict user account creation

9.3.7. How do I find the corresponding file for a BSCW document?¶

While the meta data of a BSCW document is kept in the database, the raw document itself is stored within the file system in a directory tree below the directory defined by FILES (in the main server configuration file <bscw-runtime-path>/conf/config.py) which points by default to <bscw-runtime-path>/var/data/Files/.

In general documents are named with an unique identifier assigned by the BSCW system at creation time. To store the raw document this unique identifier is split into number pairs (from the right to the left; if necessary padded with a leading zero) and copied in the corresponding <FILES> sub directory. The file name of the raw document is constructed by the left most number pair with the character F and the document type extension appended. For example, the content of a Word document with unique identifier 12345 is stored in a file named <FILES>/01/23/45F.docx.

You may retrieve meta-information on a document using the bsadmin ls utility. To get information on the above document use:

$ bin/bsadmin ls <FILES>/01/23/45F.docx

Keywords: BSCW document, document raw file

9.3.8. May I remove the contents of the BSCW “Temp” directory?¶

The BSCW “Temp” directory (<bscw-runtime-path>/var/data/Temp by default) holds temporary files and directories created during database updates and document uploads. Before removing any files from Temp, shut-down the BSCW database server. After shut-down, all files or directories beginning with a @ in “Temp” may be removed.

Keywords: temp directory, remove files from temp-directory

9.3.9. How do I upgrade my BSCW server instance to a new version?¶

Important: Read attentively the upgrade hints in section 2.4 Upgrading to BSCW 7.5.4. To perform an upgrade you need a valid BSCW license! Do not upgrade if your license has become invalid!
Download and extract the BSCW distribution archive bscw-7.5.4-<rev>-py3*.tar.gz
```
# tar xzf bscw-7.5.4-<rev>-py3*.tar.gz
```
- Enter the distribution directory bscw-7.5.4-<rev>-py3* and perform the usual installation steps (see Installation) on top of your old BSCW instance in <bscw-runtime-path>. To start the installation extract the BSCW distribution archive and run the install.sh script as superuser
```
# id
uid=0(root) gid=0(root) groups=0(root)
# tar xf bscw-7.5.4-<rev>-py3*.tar.gz
# cd bscw-7.5.4-<rev>-py3*
# ./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 5.2.6 [/opt/bscw/srv/bscw.domain.org]
 ( 1) create new BSCW instance
Enter a number (0-2): 0
...
```
- Adopt your Apache HTTP server settings (see section 3.4.1 Apache HTTP Server Configuration);
- Edit the BSCW main server configuration file <bscw-runtime-path>/conf/config.py and adapt it to your needs, e.g. enable new features (be sure to configure the mandatory settings section (see section 3.4.2 BSCW instance configuration)).
If your license got invalid apply for a “change license”:
- Make sure you are BSCW administrator (if needed, insert your user name in <bscw-runtime-path>/conf/config.py:SERVER_ADMINS) and open [Admin] in the users’ menu in the right upper corner of the interface.
  
  Log in a second time with your password to gain BSCW administrator rights for the current session and apply with
```
[Admin > Upgrade license]
[OK]
```
- Fill in the form (be sure to enter a valid email-address!)
  - Choose the license type:
    Change license for new server (royalty free)
  - Please print and fax the shown license agreement to us.

Keywords: server upgrade, new version

9.3.10. How do I migrate a BSCW database to another host?¶

Note

BSCW servers version 3.2 or later must have a valid license before the migration (resp. upgrade). If the license is not valid or is an evaluation license, you need to upgrade your license before migrating.

The procedure is as follows:

Install the same BSCW server version in <bscw-runtime-new> on your destination host
- edit <bscw-runtime-new>/conf/config.py :
  - adapt the import configuration settings of your old server (e.g. <bscw-runtime-old>/conf/config.py: SERVER_ADMIN, SERVER_ADMINS, SMTP_HOST)
  - set SERVER_ROOT = 'https://<bscw.domain.org>/' (see SERVER_ROOT)
- check if your newly installed BSCW server is fully operational
- stop your new BSCW server.
Copy the old BSCW server (in <bscw-runtime-old>) data to you new BSCW server (in <bscw-runtime-new>)
- stop your old BSCW server (in <bscw-runtime-old>)
- copy the content of the <bscw-runtime-old>/var/data directory into the <bscw-runtime-new>/var directory of your new BSCW server.
- start your new BSCW server (in <bscw-runtime-new>)
Make sure you are BSCW administrator (if needed, insert your user name in <bscw-runtime-new>/conf/config.py: SERVER_ADMINS) and open [Admin] in the users’ menu in the right upper corner of the interface.

Log in a second time with your password to gain BSCW administrator rights for the current session and press [OK]. Now apply for a new license with
```
[Admin > Upgrade license]
[OK]
```
Fill in the form (be sure to enter a valid email-address!) and choose the license type Change license for new server (royalty free). Please print and sign the shown license agreement and fax or send document (scanned) by email to us.
As soon your license is granted you will receive an email notification:
- follow the mentioned URL
- perform a garbage collection and
- restart the BSCW database server.

Keywords: migrate database

9.3.11. Why do I get a “license expired” error?¶

You may get one of the following types of errors:

The BSCW server responds with

Error: license expired
Cannot commit changes to database because the BSCW license has expired
Error code: unauthorized

In this case your BSCW database does not contain a valid BSCW license (e.g., you upgraded a BSCW server before version 3.2). To install a BSCW test license (90 days for 200 users) run the garbage collector.

The BSCW server responds with

Error: license expired
Cannot commit changes to database because the BSCW license has expired
Error code: ... <some message different from 'unauthorized'>

Your BSCW license is invalid (a more descriptive reason is shown in the error code message). In this case you have apply for a new license. Use the “Upgrade license” operation in the administrator interface.

Keywords: BSCW-license, license expired

9.3.12. Changing the “SERVER_ROOT” without service interruption¶

The BSCW license will become invalid whenever the SERVER_ROOT or the secure prefix path within the SCRIPTS dictionary is changed! This applies for example when the SERVER_ROOT is changed from HTTP to HTTPS.

To change your license without service interruption see the BSCW Admin Manual 7.5 (https://www.bscw.de/files/Download/AdminManual75.pdf) chapter 8 BSCW license.

Keywords: BSCW-license, license change

9.3.13. The BSCW server does not work, the database seems to be corrupted¶

Your database seems to be corrupted! This may only happen, if there is a (disk) hardware failure or your BSCW disk partition is overflown. A corrupted BSCW database is typically indicated by one (or all) of the following Messages (see in <bscw-runtime-path>/var/log the log files bscw.log and sys.log):

The BSCW server reports the a System error to a client and the <bscw-runtime-path>/var/log/sys.log file contains a traceback like:
```
Traceback (innermost last):
    [...]
TypeError: unsubscriptable object
```

The garbage collector reports the following traceback:

GC init:
GC started: objects: 1767 size: 1485369
Bad object 1663 at 1468966
Traceback (innermost last):
    [...]
RuntimeError: Bad objects in database

The BSCW database server reports the following traceback:

Traceback (innermost last):
    [...]
EOFError: EOF read where object expected

The BSCW database server reports the following error:

$ bin/bsadmin start
Service start bs_servdb at ('localhost', 12964)
FATAL ERROR. Server stopped
exceptions.ValueError at 1368966 (size 1485369): bad marshal data

The BSCW database server reports some other strange things in the <bscw-runtime-path>/var/log/bscw.log file.

The recommended fix is replacing the BSCW database (the file <bscw-runtime-path>/var/data/Store) by some backup file. Use the following commands with extreme care to avoid any data loss. Back up your database storage files! If in doubt ask support@orbiteam.de for further advice!
```
$ bin/start_servers -k
$ bin/bsadmin getconfig RESTORE
<bscw-runtime-path>/var/data/Store        # database store
$ cp var/data/StoreA        var/data/StoreA.bak
$ cp var/data/StoreB        var/data/StoreB.bak
$ rm var/data/StoreA        var/data/StoreB
$ rm -f var/data/Tables
$ cp var/data/Backup        var/data/Store
$ bin/start_servers
```

If your backup is outdated, or the backup files are corrupted either, you may fix the database by truncating corrupted objects using the command:

bin/bsadmin dbscan

This command will print the offsets and class names of the last objects in the database. A good choice for truncation will be the offset of the last AccessCount or Preference object. Transactions in BSCW are normally finished by writing a bunch of AccessCount or Preference objects. The database will not become inconsistent if some of these objects are missing. However you may not truncate at an offset lower than the file size after the last garbage collection (see <bscw-runtime-path>/var/data/bscw.log).

For database truncation use

$ bin/start_servers -k
$ bin/bsadmin getconfig STORE               # get active database store
<bscw-runtime-path>/var/data/StoreA
$ cp var/data/StoreA           var/data/StoreA.bak
$ bin/bsadmin dbscan -f offset
$ bin/start_servers

The parameter offset needs not to be given, if the last object in the database is an AccessCount or a Preference. Otherwise, the best value for offset is the number shown before the last AccessCount or Preference object.

Keywords: BSCW database corruption

9.3.14. Why do I get connect problems during “Upgrade License”?¶

You are probably sitting behind a firewall which does not let you connect to our license server. Here is what to do:

Use the [Upgrade license] button, but now store the returned page on your locally using [Save as] in your browsers file menu. For example, store the page in file license.html.

Alternatively you may use the command line script bsadmin license -r which creates a file <bscw-runtime-dir>/var/data/Temp/license.html.

The next 2 steps must be performed on systems which can connect to our server https://bscw.orbiteam.de.
Open the previously stored "license.html" page on a system with internet access, select [New license], choose the required license and submit the form.
If necessary print, sign, scan and send the resulting license agreement to OrbiTeam (license@orbiteam.de).
After your license is granted you will be notified by email. Open again the stored license.html page again on a system with internet access and select [Get license]. Then save the returned page on your local system (e.g. in file granted.html).
The last step again needs connection to your BSCW server (the one behind the firewall):
Open the stored license (URL file:granted.html) on a system with access to your BSCW server and select [Upload license].

Keywords: Upgrade license, connect problems, firewall

9.3.15. My BSCW database seems to be corrupt, what can I do?¶

If your BSCW database is corrupt, e.g. due to hardware failure, your BSCW database server can be enabled to do an “auto-repair” - version 3.4 onwards only!

Stop the database server:
```
$ bin/bsadmin stop
```
Important: Backup your database storage files!
```
$ bin/bsadmin getconfig STORE
<bscw-runtime-path>/var/data/StoreA
# active database store
$ mkdir var/data/backup
$ cp var/data/Backup var/data/backup
$ cp var/data/StoreA var/data/backup
$ cp var/data/StoreB var/data/backup
```
Note

The command bsadmin getconfig STORE will return the active database store (StoreA` or StoreB) while bsadmin getconfig RESTORE will return the current value of variable STORE in your configuration file

Set error condition (remove the table file if existing and create a file with “Error” appended instead)
```
$ tables=$(bin/bsadmin getconfig TABLES)
$ rm -f "$tables"
$ echo > "$tables"Error
```
Start the database server (auto-repair is enabled) after you made a backup copy of your database storage files
```
$ bin/start_servers
```

You might also use bsadmin start here.

Check for inconsistencies
To avoid user interferences set in <bscw-runtime-path>/conf/config.py SYS_BUSY = 'sys_busy' and repeat the following two steps until no errors are reported (there should be only a few repairable errors):
```
$ bin/bsadmin dbcheck list
$ bin/bsadmin dbcheck repair
```
Finally, if everything seems ok, set again in <bscw-runtime-path>/conf/config.py SYS_BUSY = '' and start the garbage collection
```
$ bin/bsadmin garbage
```

Keywords: BSCW database corrupt, database problems

9.4. BSCW Installation¶

9.4.1. What do I need to install the BSCW server software?¶

Generally you require a standard Web server (we recommend the Apache HTTP server 2.4 for Unix (https://httpd.apache.org). You also require the interpreter and standard libraries for the Python 3 programming language. The Python implementation is copyrighted, but is freely usable and can be downloaded from https://www.python.org.

9.4.2. Where should I install the BSCW server software (Unix)?¶

The installation program of the BSCW software must be run as superuser (root). The BSCW install procedure will create a special BSCW system user bscw with an own group bscw. Usually the BSCW software is installed in the home directory of the BSCW system user at /opt/bscw.

It is necessary that your Web server have access to the file system where BSCW is installed. For best performance use a local file system of the host where your Web server runs.

Keywords: BSCW server installation, operating system

9.4.3. Why do I get a “500 Server Error” when I try to register myself?¶

When you try to register, i.e., when you go to location

https://<server>/pub/bscw.cgi?op=rmail

and you receive "500 Server Error" your Web server failed to start the BSCW bscw.cgi CGI script. Check that your Web server runs on the same host as the BSCW database server - both servers must run on the same host.

Also check that the paths to the BSCW CGI script bscw.cgi, the Python interpreter (usually /usr/bin/python3) and the Python libraries (usually /usr/lib/python3.*/) are accessible from the server host machine for the user (group) ID that the Web server uses to execute CGI scripts.

Keywords: BSCW-registration, register, 500 Server Error

9.4.4. Can I put the data files for the server on a separate disk?¶

On Unix systems you can change in <bscw-runtime-path>/conf/config.py the location of various data files by appending the directory definition for ALARM_DIR, DATA_DIR, LOG_DIR, RUN_DIR, WWW_DIR.

Note

If you provide relative paths directories are relative to <bscw-runtime-path>.

Keywords: data files, separate disk, operating system

9.4.5. What can I do if I get a `ServiceException: getState, ()` error¶

In <bscw-runtime-path>/conf/config.py change (or add a line):
```
GSMOD_CAN_FLUSH = 0
```
Stop the running database server:
```
$ bin/start_servers -k
```
Check if stopping the database server was successful:
```
$ ps -ef | grep bsadmin
```
There should be no process bsadmin start ... running. Otherwise manually kill this process:
```
$ kill <pid of bsadmin process>
```
(Be careful if you have other BSCW servers running on your machine that you don’t want to kill.)
Start database server:
```
$ bin/start_servers
```

Keywords: ServiceException, start_servers

9.4.6. How can I provide a BSCW user interface in different languages?¶

BSCW was designed to allow installation of different language interfaces. Therefore server code and language dependent message files have been separated. All message files reside in a sub directory of the BSCW distribution bscw-7.5.4-<rev>-py3*/bscw/msg (e.g. msg/(de|en|es|fr) come with the server distribution).

To add support for additional languages see section 7.1.2 Translation instructions of this manual.

If you translated the BSCW user interface to your language, please send an email to support@orbiteam.de - we would like to provide it to all users of the BSCW system.

Keywords: user interface, languages, message files

9.4.7. Why do I get a `"Permission denied"` error? (Unix)¶

The path to your BSCW instance directory, the <bscw-runtime-path>/var/www directory and all directories below these directories must be readable and executable (searchable) for all users (e.g. mode drwxr-xr-x). The scripts var/www/*.cgi additionally must have the set-group bit set (e.g. mode –rwxr-sr-x). All other files below these directories must be readable for all. This is, because the HTTP server must have the right to find and execute the CGI scripts and to return icons and other public objects.

The scripts (or a wrapper program) will then set the effective group for further access to BSCW operations. All data below the BSCW installation directory should be readable by this group. This group needs also write access to the var/data/ directory and all files and directories below that.

Access right problems like

Traceback (innermost last):
    [...]
OSError: [Errno 13] Permission denied: 'var/data/Files/01/23'

are caused by an erroneous installation of the bscw.cgi CGI script (no binary wrapper is installed, the script is not executed set-group-id of the BSCW users’ group; the BSCW instance-path file system is mounted no-suid) or by incorrect manual manipulation of the BSCW instance-path access rights.

BSCW requires group-write permissions (therefore it requires an own exclusive group. Please check the section 3.2 Installation of this manual for correct BSCW user and group setup.

Execute as BSCW user bscw with the group bscw the bsadmin chkconfig script:

# su bscw
$ id
uid=1234(bscw) gid=1234(bscw)
$ cd <bscw-runtime-path>
$ ./bin/bsadmin chkconfig

This should compile (if a compiler is found) and install a binary wrapper. If no compiler is found compile the wrapper manually and repeat bsadmin chkconfig. The bscw.cgi CGI script must run set-group-id and the complete BSCW ./var/data directory needs rws-group access.

To fix erroneous file permission stop your BSCW server and perform the following commands (as root)

$ su -
$ id
uid=0(root) gid=0(root)

# cd <bscw-runtime-path>

# ./bin/start_servers -k

# chown -Rh bscw:bscw .

# find ./var/[^w]* -type d | xargs chmod 2770
# find ./var/[^w]* -type f | xargs chmod 660

# find ./var/www -type d | xargs chmod 2775
# find ./var/www -type f | xargs chmod 664

# chmod 2755 .

# chmod 2755 ./var/run/run_bscw
# chmod 2755 ./var/www/bscw.cgi
# chmod 2755 ./var/www/nj_bscw.cgi

# chmod 2771 ./var/data

To avoid world read-access on ./var/data/htpasswd (or ./var/data/Temp) the file (or directory) alternatively must be owned by the webserver user (see the User directive in the main HTTP server configuration file). On Debian Linux ensure the following ownership/permissions

$ su -
$ id
uid=0(root) gid=0(root)

# cd <bscw-runtime-path>

# chown www-data        ./var/data/expired_users
# chmod 660             ./var/data/expired_users

# chown www-data        ./var/data/htpasswd
# chmod 660             ./var/data/htpasswd

# chown www-data        ./var/data/registered_users
# chmod 660             ./var/data/registered_users

# chown www-data        ./var/data/removed_users
# chmod 660             ./var/data/removed_users

# chown -Rh www-data    ./var/cache/preview
# find ./var/cache/preview -type d | xargs chmod 2770

# chown -Rh www-data    ./var/data/Temp
# find ./var/data/Temp -type d | xargs chmod 2770

# chown -Rh www-data    ./var/log
# chmod 2770            ./var/log

Since Linux environments do not execute forked processes set-group-id, archiving may not work anymore. To create archives it is necessary to recursively change the owner the ./var/data/Files directory to the web server user.

$ su -
$ id
uid=0(root) gid=0(root)

# chown -Rh www-data ./var/data/Files

# ./bin/start_servers

Keywords: Permission denied, HTTP server, OSError, Unix

9.4.8. Why do I get a `"RuntimeError: var/www/bscw.cgi: No setgid"`?¶

If your operating system does not support set-group-id scripts (such as Linux) a binary wrapper program is used to allow set-group-id operation of the bscw.cgi script. If your operating system supports set-group-id scripts, this problem is caused by a file mode/ownership problem.

Usually the BSCW CGI script (<bscw-runtime-path>/var/www/bscw.cgi) is executed with group ID set to the BSCW user:

$ cd <bscw-runtime-path>/var/www
$ ls -l bscw.cgi
-rwxr-sr-x 3 bscw bscw 771 Feb 21 13:12 bscw.cgi

Using this technique enables the BSCW CGI script (independently of the user and group ID setting of the executing HTTP server) to modify its database located in directory <bscw-runtime-path>/var/data:

$ cd <bscw-runtime-path>/var
$ ls -ld data
drwxrws--- 4 bscw bscw 512 Feb 21 14:05 data

The problem should be solved by changing file ownership and modes (using user and group ID of the BSCW user) as described in FAQ question 9.4.7 Why do I get a "Permission denied" error? (Unix).

Keywords: Python traceback, RuntimeError, CGI scripts, operating system

Windows	IE	Office	Protocol	BSCW >=	Edit
*	*	*	HTTP	*	no
10 64bit	Edge	Office 2016	HTTPS	7.1.0	yes
10 64bit	Edge	Office 2016	HTTPS	7.1.0	yes

9. Frequently Asked Questions (FAQ)¶

9.1. BSCW Server Usage¶

9.1.1. What do I need to use BSCW?¶

9.1.2. Do I need a special application for uploading documents?¶

9.1.3. How is BSCW intended to be used¶

9.1.4. I cannot log in. The server rejects me - what shall I do?¶

9.1.5. How do I change my password?¶

9.1.6. How do I connect to BSCW using WebDAV?¶

9.1.6.1. How to connect to BSCW using WebDAV on Windows 11¶

9.1.6.2. Troubleshooting¶

9.1.6.3. Hints for Windows 11¶

9.1.6.4. Hints for BSCW administrators¶

9.1.7. How do I destroy a workspace?¶

9.1.8. How do I delete my account?¶

9.1.9. How do I handle a BSCW error?¶

9.1.10. I reached the limit of my disk space - what shall I do?¶

9.1.11. Why does MS-Word mark a document as read-only?¶

9.1.12. Is there a restriction for the size of documents I upload?¶

9.2. BSCW Server Software¶

9.2.1. How do I get the BSCW software?¶

9.2.2. Can I try the BSCW software?¶

9.2.3. How do I keep up to date with BSCW developments and new releases?¶

9.3. BSCW Server Administration¶

9.3.1. What facilities are available for server administrators?¶

9.3.2. How do I delete a user from the BSCW server?¶

9.3.3. How do I rename a user?¶

9.3.4. How do I register a new user (i.e. without sending email)?¶

9.3.5. How do I restrict the creation of workspaces?¶

9.3.6. How do I restrict the creation of new user accounts?¶

9.3.7. How do I find the corresponding file for a BSCW document?¶

9.3.8. May I remove the contents of the BSCW “Temp” directory?¶

9.3.9. How do I upgrade my BSCW server instance to a new version?¶

9.3.10. How do I migrate a BSCW database to another host?¶

9.3.11. Why do I get a “license expired” error?¶

9.3.12. Changing the “SERVER_ROOT” without service interruption¶

9.3.13. The BSCW server does not work, the database seems to be corrupted¶

9.3.14. Why do I get connect problems during “Upgrade License”?¶

9.3.15. My BSCW database seems to be corrupt, what can I do?¶

9.4. BSCW Installation¶

9.4.1. What do I need to install the BSCW server software?¶

9.4.2. Where should I install the BSCW server software (Unix)?¶

9.4.3. Why do I get a “500 Server Error” when I try to register myself?¶

9.4.4. Can I put the data files for the server on a separate disk?¶

9.4.5. What can I do if I get a ServiceException: getState, () error¶

9.4.6. How can I provide a BSCW user interface in different languages?¶

9.4.7. Why do I get a "Permission denied" error? (Unix)¶

9.4.8. Why do I get a "RuntimeError: var/www/bscw.cgi: No setgid"?¶

9.4.5. What can I do if I get a `ServiceException: getState, ()` error¶

9.4.7. Why do I get a `"Permission denied"` error? (Unix)¶

9.4.8. Why do I get a `"RuntimeError: var/www/bscw.cgi: No setgid"`?¶