4. Configuration of BSCW Servers¶

The BSCW server can be configured by a set of configuration files which are stored in the instance configuration directory <bscw-runtime-path>/conf/. The standard configuration files in the instance configuration directory <bscw-runtime-path>/conf/ are:

config.py General configuration of the BSCW server
config_actions.py Customization to default action or role definitions
config_cal.py Configuration of the calendar
config_clientmap.py Configuration of web browser capabilities
config_controls.py Customization to default operation control definitions
config_convert.py Specification of encoders, converters, programs
config_countries.py Specification of country codes
config_grid.py Webbrowser grid layout
config_guided_tours.py Guided tour definitions
config_help.py Contains online help mappings
config_html_ui.py HTML user interface
config_icon.py Icon definitions
config_meet.py Configuration of social network facilities
config_menus.py Configuration of the menu layout
config_metadata.py Configuration of meta data
config_mimegroups.py Application MIME-type grouping
config_mime_icons.py MIME-type icons
config_mimemsg.py Additional translations for MIME-type specification
config_mime.py MIME-type specifications
config_mpick.py Define class substitutions for deactivated packages
config_prio_categ.py Configuration of priorities and categories
config_quicksearch.py Settings for quick search
config_search.py Search configuration
config_styles.py Settings for style sheet handling

Please note the editing instructions within these files carefully when making any modifications. It should be noted that all configuration files are Python modules and on thus subject to Python’s programming language syntax. After an overview of different user authentication possibilities, the above configuration files are described in this section.

4.1. Authentication¶

BSCW provides for each user a personal view of accessible data. To access this personal view on the BSCW system every user needs to authenticate with an individual user name or an email address (allocated to an user name) and a password. In general BSCW offers two possibilities to perform this authentication

BSCW Authentication

In general BSCW authentication is passing user credentials via an environment variable to BSCW (cookie / basic / digest authentication). Passing the users’ credentials to BSCW gives the most flexibility to react on authentication challenges.

See also

Section 2.2 Security considerations

Using BSCW authentication enables the usage of different (configured) methods, for example such as querying an LDAP service for users with an LDAP binding, or redirect to a single sign on service to perform an external user authentication.

Additional features like
- authentication with (registered) email address and password
- BSCW logout
- automatic fall-back to basic / digest authentication for WebDAV clients (since the WebDAV protocol does not support cookie authentication).
are only available using BSCW authentication.
Web Server Authentication

Web Server Authentication used to be the classical” way BSCW handled authentication. To utilize the Apache web serves’ basic authentication module the (encrypted) user credentials are stored within a file htpasswd (see PASSWD) which was shared between the BSCW server and the Apache web server.

While BSCW maintains this file, the Apache web server uses it to check the given user credentials before BSCW may be accessed via its bscw.cgi script.

Using web server based authentication allows a “cascading” use of diverse Apache authentication modules. This enables for instance the implementation of an efficient authentication lookup against an organizational LDAP service (using the Apache mod_ldap.so). For failed LDAP authentication attempts then as second stage the standard basic authentication method is invoked using the shared htpasswd file.

Nevertheless Apache web server authentication may not be flexible enough and has the following limitations:
- authentication with email address and password is not possible, since at login time the web server cannot check the association between allocated email address and user name
- the BSCW logout feature is not available
- the usage of the ZOPE external editor is not possible (due to the used authentication mechanism).
Note

By default the creation of the PASSWD file is disabled, so no shared htpasswd file is generated.

BSCW instances enable BSCW authentication using Cookie Authentication as default setting. On older BSCW instances BSCW authentication may be explicitly enabled by running the command line script

$ bin/bsadmin conf_apache -n

4.2. conf/config.py¶

This file defines the general server settings and server configuration of the BSCW server instance. Please note all relative file and directory names are resolved using instance runtime directory <bscw-runtime-path>.

Important

By using the pre-forking BSCW HTTP server (http package) all configuration changes only take effect after a restart of the BSCW HTTP server, which is performed from the CLI running:

bin/bsadmin http restart

or on the administration BSCW status page [Options ‣ Admin ‣ Status] by clicking the [Restart integrated http service] entry.

Below the names of the configuration variables, their meaning and their default settings are given. At least the variables mentioned in the Section 1: MANDATORY server settings the configuration file must be set since their default setting is not sufficient.

4.2.1. MANDATORY server settings¶

SERVER_ROOT

The Web servers’ root address. This should be an absolute URL specifying

the protocol (http or https)

the fully qualified domain name of the server (a numeric IP address is not allowed here)

and (optionally) the port number

See section 3.4.2 BSCW instance configuration for configuration hints of SERVER_ROOT. For example
SERVER_ROOT = 'http://bscw.domain.org'
SERVER_ROOT = 'http://bscw.domain.org:8000
SERVER_ROOT = 'https://bscw.domain.org'
Note

You have to set SERVER_ROOT before you apply for a BSCW license.

A granted BSCW license (not the evaluation license) will become invalid if you change SERVER_ROOT or the SCRIPTS prefix (see below). In this case BSCW will complain with a “license error” message after the BSCW database server is restarted or the garbage collector has run. Hence, you need to apply for a new (royalty-free) “change server”- license after changing the values of SERVER_ROOT or the standard SCRIPTS prefix. Of course, you might also reset SERVER_ROOT and SCRIPTS to the old values and restart (stop and start) the BSCW database server.

SERVER_ROOT = 'https://bscw.domain.org'

SERVER_ADMIN

The mail address of the BSCW administrator. It must be set to a valid and complete mail address.

SERVER_ADMIN = 'admin@domain.org'

SERVER_ADMINS

USER_ADMINS

Define lists of users with different administrative rights:

SERVER_ADMINS is a list of BSCW users that have full administrator rights (including user administration), e.g.:
SERVER_ADMINS = ['admin', 'alice', 'bob']
USER_ADMINS defines a list of BSCW users that have restricted administrator rights to manipulate (create, remove, change etc.) users and mail addresses only, e.g.:
USER_ADMINS = ['carol', 'dave']
Note

The users listed here must be registered BSCW users and the names must match exactly.

See also

SERVER_ADMINS_IP for domain restrictions

SERVER_ADMINS = ['admin']
USER_ADMINS = []

SERVER_ADMIN_CONTACT

The mail contact address of the BSCW administrator. This is used to reference SERVER_ADMIN_CONTACT in the index page and the help menu for end users to contact their BSCW administrator by e-mail.

If left empty, the SERVER_ADMIN e-mail address is used.

SERVER_ADMIN_CONTACT = ''

HTTP_LOCAL_PORT

HTTP_LOCAL_PORT_START

HTTP_LOCAL_HOST_CHECK

HTTP_LOCAL_PORT defines the localhost port to HTTP server. BSCW needs local access to the standard bscw.cgi script. The HTTP server must listen to localhost:<HTTP_LOCAL_PORT> and must provide access to the BSCW Server via this port.

Note

the localhost port to the HTTP server must support HTTP; HTTPS is not supported.

If you use the Apache <VirtualHost> container to accommodate the BSCW script path it may be necessary define an extra virtual host for localhost:<HTTP_LOCAL_PORT> where the Apache configuration file <bscw-runtime-path>/conf/apache24/bscw.conf also is included.

See also the virtual host container template file <bscw-instance-path>/conf/apache24/site.conf for examples.

If HTTP_LOCAL_PORT_START is not None and the package http is enabled then bsadmin start automatically starts a HTTP server listening on HTTP_LOCAL_PORT. For example, with HTTP_LOCAL_PORT_START = "-p 100 -r 128" the command bsadmin start automatically executes bsadmin http -p 100 -r 128 local (spawning maximal=100 processes with maxlisten=128, this is the default).

Use bsadmin conf_apache in order reconfigure the Apache server to forward requests to this server instead of executing bscw.cgi scripts. You must reconfigure and restart Apache again if you reset HTTP_LOCAL_PORT_START = None, change HTTP_LOCAL_PORT or disable the http package!

Note

Currently bsadmin http and hence HTTP_LOCAL_PORT_START works only on Unix systems!

If HTTP_LOCAL_PORT_START is not None, then check for special authentication (used by op_alarm, op_mailnotify etc.) that REMOTE_ADDR is one of the given local host addresses, e.g: HTTP_LOCAL_HOST_CHECK = ('::1', '127.0.0.1')

HTTP_LOCAL_PORT = 80
HTTP_LOCAL_PORT_START = None
HTTP_LOCAL_HOST_CHECK = ('::1', '127.0.0.1')

EVENTS_SERVER_WS

EVENTS_SERVER_HTTP

Define local endpoints for the real-time events server. Requires a node runtime environment and additional setup steps. Please refer to the admin manual for details.

EVENTS_SERVER_WS defines the URL of events server websocket, e.g. ‘ws://127.0.0.1:3836’. User browsers connect to this endpoint through a reverse proxy, offered by the HTTP server.

EVENTS_SERVER_HTTP defines the URL of events server http, e.g. ‘http://127.0.0.1:3837’. Internal endpoint for event and login data exchange.

EVENTS_SERVER_WS = None
EVENTS_SERVER_HTTP = None

CONFERENCE_PROVIDER

CONFERENCE_VERSION

CONFERENCE_HOST

CONFERENCE_PORT

CONFERENCE_SECRET

Define an endpoint for real-time conferences via webcam and/or microphone. Requires a ready configured conference service.

Currently the following conference services are supported:

Jitsi (https://github.com/jitsi/jitsi-meet) A installation guide can be found at https://jitsi.github.io/handbook/docs/devops-guide/devops-guide-quickstart

BigBlueButton (https://bigbluebutton.org) A installation guide can be found at https://docs.bigbluebutton.org/3.0/install.html

BSCW utilizes two deployment methods dependent on CONFERENCE_SECRET setting (see below):
JSON web token authentication (RFC 7519) connection to the conference server. It is utilized if CONFERENCE_SECRET is defined. In this case a proxy configuration of BSCW (as described below) is not used.
Reverse proxy connection through BSCW to the conference server. After each change to one of the following CONFERENCE_* directives, bsadmin conf_apache -T must be run again and the web server must be restarted. This creates an additional Apache HTTP server configuration file service_token.conf with a unique URL token for accessing the conference server. It is recommended to recreate this token regularly (e.g. once a day) by running bsadmin conf_services via cron and restarting the Apache HTTP server, e.g.
10 01  * * * /opt/bscw/srv/<bscw-instance>/bin/bsadmin conf_services
CONFERENCE_PROVIDER defines the conference provider, either "JITSI" for Jitsi or "BBB" for BigBlueButton

CONFERENCE_VERSION allows to set the configuration for a specific version of the conference provider. The value default uses the preconfigured settings. For details see the configuration file conf/config_<provider>.py (e.g. config_jitsi.py for Jitsi) or the administrator manual office package description.

CONFERENCE_HOST defines for the “JITSI” provider the URL to the conference server, (e.g. https://jitsi.org). All provider definitions assume a scheme (http:// or https:// before the domain or IP address).

CONFERENCE_PORT defines the port of the conference server. With CONFERENCE_PORT = None (default) the default value for the provider is used (which is for “JITSI” and “BBB” 443).

CONFERENCE_SECRET defines a shared secret key between BSCW and the conference server.

Warning

In order not to compromise the security of the conference server, this key must never be shared.
for the “JITSI” provider additionally the installation of
the Python PyJWT package for the BSCW server Python version is required, e.g
$ pip3 install pyjwt
the jitsi-meet-tokens plugin for prosody on the Jitsi server is required. Follow then the instructions for jwt support in Jitsi: https://github.com/jitsi/lib-jitsi-meet/blob/master/doc/tokens.md
for the “BBB” provider use the command bbb-conf --secret
on the conference server to get the secret key.

CONFERENCE_PROVIDER = 'JITSI'
CONFERENCE_VERSION = 'default'
CONFERENCE_HOST = None
CONFERENCE_PORT = None
CONFERENCE_SECRET = None

INHERIT_BANNER_IMAGE

Defines whether a background image in the area of the banner should be passed over the content display or not.

Set INHERIT_BANNER_IMAGE to True if the background image inside the banner should be passed over and False else

INHERIT_BANNER_IMAGE = True

ENABLE_LIVE_COMMUNITY

SHOW_CURRENT_CONTEXT_INDICATION

SHOW_UPCOMING_PERSONAL_TASKS

Enables or disables the live realtime information sharing of BSCW members relating to current context and next upcoming tasks

ENABLE_LIVE_COMMUNITY: Enables/Disables everything related to the live community. Set True if the live community should be activated and False else.

SHOW_CURRENT_CONTEXT_INDICATION: Enables/Disables the flying avatars which indicates the current context of the corresponding user. Set True if the live community should be activated and False else.

SHOW_UPCOMING_PERSONAL_TASKS: Enables/Disables the sharing of tasks in the personal task list of each member of the BSCW server who is a participant of the live community. Set True to activate and False else.

ENABLE_LIVE_COMMUNITY = True
SHOW_CURRENT_CONTEXT_INDICATION = True
SHOW_UPCOMING_PERSONAL_TASKS = True

OFFICE_PROVIDER

OFFICE_VERSION

OFFICE_HOST

OFFICE_PORT

OFFICE_SERVER_ROOT

OFFICE_JWT_SECRET

OFFICE_JWT_HEADER

OFFICE_FORCE_SAVE

define the endpoints for Online Office providers. After each change of one of the following OFFICE_* directives, bsadmin conf_apache must be executed again and the web server restarted.

OFFICE_PROVIDER defines the office provider, either “OO” for ONLYOFFICE or “MS” for Microsoft 365 or “C” for Collabora Office (deprecated)

OFFICE_VERSION allows to set the configuration for a specific version of the Online Office provider. The value ‘default’ uses the preconfigured settings. For details see the configuration file conf/config_<provider>.py (e.g. config_oo.py for ONLYOFFICE) or the administrator manual office package description.

All provider definitions assume a scheme (http:// or https:// before the domain or IP address). OFFICE_HOST defines

for the “OO” provider

the URL to the ONLYOFFICE documentserver (e.g. http://localhost).

for the “MS” provider

the full WOPI discovery URL, as provided by a Microsoft 365 provider. To enable Microsoft 365 with your BSCW instance a DNS entry into the domain wopi.bscw.de is required, ask support@orbiteam.de for details.

for the “C” provider

the IP address of the Collabora Online Office service (deprecated). By default, the IP address of Collabora Online Office is set to ‘127.0.0.1’. (Note: Due to lack of customer demand, only versions up to 4.0.9 are supported).

OFFICE_PORT defines the port of the Online Office service. By default, Collabora uses port 9980, and MS Office and ONLYOFFICE use port 443. With OFFICE_PORT = None (default) these values are used.

OFFICE_SERVER_ROOT defines an alternative (second) URL of the BSCW instance for use in local DMZ environments where the ONLYOFFICE service is not publicly accessible.

If defined, all requests are redirected via BSCW so that the URL of the ONLYOFFICE service is not exposed. By default, OFFICE_SERVER_ROOT is undefined (None) and the ONLYOFFICE service is connected directly via its publicly accessible URL.

OFFICE_JWT_SECRET defines a JSON web token shared between BSCW and ONLYOFFICE. Set OFFICE_JWT_SECRET to the ONLYOFFICE token definition (see /etc/onlyoffice/documentserver/local.json: services.secret.{inbox|outbox|session}.string). If defined, the Python package PyJWT must also be installed. Furthermore, OFFICE_JWT_HEADER must be set to the name of the HTTP header field used by ONLYOFFICE (as defined in /etc/onlyoffice/documentserver/local.json: services.token.{inbox|outbox}.header, usually ‘Authorization’)

Note

BSCW will redirect (proxy) all requests to the ONLYOFFICE service via the BSCW apache HTTP server if one of the following conditions is met:

OFFICE_SERVER_ROOT is defined

OFFICE_JWT_SECRET or OFFICE_JWT_HEADER are undefined

If the ONLYOFFICE service is exposed directly to the internet, it must support an SSL URL and OFFICE_HOST must start with https://.

OFFICE_FORCE_SAVE (for “OO” provider only) If set to True, the edited document will be saved before another user may take over the document lock (default: OFFICE_FORCE_SAVE = True).

OFFICE_PROVIDER = 'OO'
OFFICE_VERSION = 'default'
OFFICE_HOST = 'http://127.0.0.1'
OFFICE_PORT = None
OFFICE_SERVER_ROOT = None
OFFICE_JWT_SECRET = None
OFFICE_JWT_HEADER = 'Authorization'
OFFICE_FORCE_SAVE = True

SMTP_HOST

SMTP_AUTH

A host name or an IP-address of a mail host that accepts mail posting by SMTP.

Using the SMTP_HOST option is recommended, because it allows to set sender addresses correctly. If empty, the local mail delivery command as defined in SENDMAIL is used (see also local BSCW mail delivery MDA_MTA). A non-default port may be specified by appending :<port>, SMTP_HOST = 'mail.bscw.de:225'

Finally @TLS or @SSL may be appended to SMTP_HOST, in order to switch over to TLS (see smtplib starttls) or to start right away with SSL (see smtplib SMTP_SSL, not supported by non-SSL builds). Invalid SMTP_HOST setting and BSCW mail transport in general can be debugged with:
bsadmin sendmail -vv
If SMTP_AUTH is set to a non-empty string login:passwd the RFC 2554 SMTP authentication mechanism is used after connecting the mail host. This string contains a pair of login name and clear text password separated by :, e.g. SMTP_AUTH = 'bscw:secret'

SMTP_HOST = 'mail.domain.org@TLS'
SMTP_AUTH = ''

4.2.2. Mail handling¶

SENDMAIL

A command line accepting mail (header+body) for posting via standard input. The patterns %(from)s and %(to)s in the SENDMAIL string are substituted by the sender and the recipients of the mail respectively (the recipients are separated by spaces).

SENDMAIL = ['/usr/lib/sendmail', '-f', '%(from)s', '%(to)s']

MDA_MTA

MDA_MBOX

MDA_DOMAIN

MDA_HDRMETA

MDA_EXTRACTMAIL

MDA_DELIMITER

MDA_EXT

Settings for the local BSCW mail delivery agent, which delivers mail directly into folders.

Note

When local BSCW mail delivery is enabled, the BSCW server should only use the local mail server, therefore it is advisable to set SMTP_HOST = ''

MDA_MTA specifies the local Mail Transfer Agent (MTA), currently supported are:
MDA_MTA = 'qmail'
MDA_MTA = 'postfix'
MDA_MTA = 'sendmail'
Setting MDA_MTA = '' or any unknown MTA will disable the BSCW mail delivery feature (this is the default).

MDA_MBOX defines the local mailbox name for BSCW mda (this is normally the BSCW user ID name)

MDA_DOMAIN defines the domain name of the BSCW MDA (which is the delivery domain of the local MTA for the local BSCW MDA mailbox)

MDA_HDRMETA defines which headers are shown in the RFC822 meta profile of an uploaded email, e.g.:
MDA_HDRMETA = ['RFC822:from', 'RFC822:to', 'RFC822:cc']
if MDA_EXTRACTMAIL evaluates to True, the ‘mailaccess’ form shows a preselected option “[x] extract emails into a folder”

MDA_DELIMITER = None (optional) allows to override the MTA default recipient delimiter:
MDA_DELIMITER = '+' (sendmail/postfix)
MDA_DELIMITER = '-' (qmail)
MDA_EXT = True (optional) appends the extension for the MIME type message/rfc822 (as defined in config_mime.py: .eml or .mht) to the email name.

MDA_MTA = ''
MDA_MBOX = 'bscw'
MDA_DOMAIN = 'domain.org'
MDA_HDRMETA = ['RFC822:from', 'RFC822:to', 'RFC822:cc']
MDA_EXTRACTMAIL = False

SEND_LIMIT

SEND_LIMIT is a tuple of (soft_limit, hard_limit). If an email should be send by the send operation and the message becomes larger than the soft_limit , the user gets an hint that, he will send a large email. If the message is larger then the hard_limit, the sending of the message will be rejected. If one or both of the limits are 0, the test or both tests will be suppressed.

Possible values for the sizes are strings which may be specified in bytes or kilo- (mega-, giga-, tera-) bytes with an additional k (K), M, G or T suffix. E.g. valid values for ten mega-bytes are 10485760 or :'10M'.

SEND_LIMIT = ('10M', '20M')

TOKEN_EXP

AUTH_TOKEN_EXP

API_TOKEN_EXP

TOKEN_EXP defines the life span of access tokens for documents sent in emails. When sending documents as links (send operation), email recipients will be sent the link including a temporary token. This token grants “get” access to the document for anonymous users, until the token expires. Setting TOKEN_EXP = None will entirely disable option to send tokens; links can then only be sent to registered users with “get” right.

AUTH_TOKEN_EXP defines the maximum validity period of a registration link (sent in user registration email notifications). By default these links do not expire (AUTH_TOKEN_EXP = None)

API_TOKEN_EXP defines the validity period of an API token used to authenticate an API request.

possible values for the interval may be specified in seconds or minutes (hours, days, weeks) with an additional 'm' ('h', 'd', 'w') suffix. E.g. valid values which specify one week are 604800 (or '604800'), '7d' or '1w'.

TOKEN_EXP < 600 sec (10 min) will entirely disable this option.

AUTH_TOKEN_EXP must be set >= 600 sec (10 min)

TOKEN_EXP = '4w'
AUTH_TOKEN_EXP = None
API_TOKEN_EXP = '2w'

SEND_ADMIN

If set it specifies an email address which will be used as sender instead of the SERVER_ADMIN, when an user sends an email via the send operation.

SEND_ADMIN = ''

SEND_RETURN_PATH

SEND_HDR

SEND_ONBEHALF

define headers of outgoing BSCW user email messages

If SEND_RETURN_PATH is set it specifies an email address, which will be used as Return-path in the envelope when mails are sent. Otherwise the email address from the From field is used (which is considered to be a valid email address, because it has been verified by BSCW).

If SEND_HDR is True (default) BSCW appends a Sender: <SEND_ADMIN> and a Reply-To: <user-mailaddr> header to honor RFC 822/4021 agent submission. If additionally SEND_ONBEHALF is True (default: False) the From: header is rewritten as From: "BSCW on behalf of <user>" <SEND_ADMIN>.

SEND_RETURN_PATH = ''
SEND_HDR = True
SEND_ONBEHALF = False

4.2.3. Server access¶

SERVER_ADMINS_IP

List (or tuple) of IPv4 or IPv6 addresses or networks. Networks may be specified in prefix (CIDR) or netmask notation. If not empty the remote address must match one of the given domains for a user in SERVER_ADMINS or USER_ADMINS to become BSCW Administrator (see below).
SERVER_ADMINS_IP = [
    '1.2.3.4',                  # administrator IP address
    '1.2.3.0/24',               # administrator IP net (prefix)
    '1.2.3.0/255.255.255.0',    # administrator IP net (netmask)
]

SERVER_ADMINS_IP = []

MAY_REGISTER

ALLOW_MAIL_AUTH

ALLOW_MAIL_UNLOCK

MAY_REGISTER defines a list of BSCW users names or pattern tuples of email addresses assigned to users who have the right to register mail addresses - i.e. to invite new users to the system or to a workspace. This is in addition to SERVER_ADMINS or USER_ADMINS who have this right anyway. Please see RESTRICT_MAIL for a description how to define pattern tuples, example
MAY_REGISTER = [
    'username',
    ('[^@]*@orbiteam.de', 1),
]
There are three special cases: if MAY_REGISTER is :

[] - registration of new email addresses is allowed for all users. This allows all registered users to invite new users to the system. Also self-registration is possible.

None - registration is allowed for all registered users, but self-registration is forbidden.

Note

Only MAY_REGISTER = [] allows self-registration by URL: https://bscw.domain.org/pub/bscw.cgi?op=rmail

If ALLOW_MAIL_AUTH is set True (default) users may reset their password via mail token authentication. If set False mail token authentication is disallowed (and only the administrator may reset forgotten passwords).

If ALLOW_MAIL_UNLOCK is set True users may unlock their account after being locked by the system (e.g. after multiple wrong login attempts (as defined in BADPASS)) via mail token authentication. If set False users may only be unlocked by a BSCW administrator.

MAY_REGISTER = None
ALLOW_MAIL_AUTH = True
ALLOW_MAIL_UNLOCK = True

MAY_CREATE_MAILADDRESS

MAY_CREATE_MAILADDRESS defines a list of BSCW user names or pattern tuples of email addresses that have the right to create external mail addresses - e.g. suggest participants for an appointment scheduling. This is in addition to users from MAY_REGISTER, who have this right anyway. Please see MAY_REGISTER and RESTRICT_MAIL for a description of special values and how to define pattern tuples, example:
MAY_CREATE_MAILADDRESS = [
    'username',
    ('[^@]*@forbidden.com', 0),
    ('[^@]*@allowed.com', 1),
]
There is another special case, which will restrict creation of new email addresses exactly to users from MAY_REGISTER:
MAY_CREATE_MAILADDRESS = False
Note

This right also enables a user to find and disclose all email addresses that are known to the system!

MAY_CREATE_MAILADDRESS = []

REGISTER_DETAILS

TERMS_AND_CONDITIONS

PRIVACY_POLICY

ACCESSIBILITY_POLICY

A list of user details that must be filled in at registration time by new users. Select a subset of the following user attributes:

fullname (users’ full name), org (Organization), phone (work phone). fax (work fax), homephone (private phone), mobile (mobile phone), post (postal address). In order to inquire the user for his full name and phone number at registration you would configure:
REGISTER_DETAILS = [
    'fullname','org', 'phone', 'fax',
    #'homephone', 'mobile', 'post'
]
or allow registration without additional details, simply set:
REGISTER_DETAILS = None
If TERMS_AND_CONDITIONS, PRIVACY_POLICY or ACCESSIBILITY_POLICY are defined and point to a link (URL), the registration form will be extended by check-boxes which the user has to confirm before finishing the registration process.

The page referenced by TERMS_AND_CONDITIONS should describe the server’s terms of use (which the users agree to accept). The pages referenced by PRIVACY_POLICY should contain rules that apply to data protection declaration (resp. “Datenschutzerklärung” [DE]) and ACCESSIBILITY_POLICY should contain a accessibility declaration (resp. “Erklärung zur Barrierefreiheit” [DE]). All links will be shown in the menu of the index page and in the footer of all (container) pages.

To support language dependent links, add the language shortcut (uppercase) to the variable name, e.g. use TERMS_AND_CONDITIONS_DE for a German page.

Note

English is the default language which is displayed for all languages without language dependent link.

With the legal validiy of the EU - General Data Protection Regulation (GDPR), it will be necessary to provide a data protection declaration for BSCW instances operated in the European Union. See the BSCW admininstration manual section 2.3 EU - General Data Protection Regulation for further details.

REGISTER _DETAILS = None
TERMS_AND_CONDITIONS = ''
PRIVACY_POLICY = ''
ACCESSIBILITY_POLICY = ''

DEFAULT_TELL_LASTLOG

Users’ default value for “Show my presence and last login date to other users”

DEFAULT_TELL_LASTLOG = True

ABOUT_SITE

If ABOUT_SITE is defined it should point to a link (URL) that contains legal notice of the server’s website (aka ‘Publisher’ [EN] or ‘Impressum’ [DE]). The link will be shown on the index page’s menu and as visible link in the footer of all (container) pages.

To support language dependent links, add the language shortcut (uppercase) to the variable name, e.g. use ABOUT_SITE_DE for a German page.

Note

English is the default language which is displayed for all languages without language dependent link.

ABOUT_SITE = ''

MAY_UNREGISTER

Defines if BSCW users have the right to unregister (i.e. self-destroy their account).

MAY_UNREGISTER may not be configured for individual accounts but only be set to True or False, i.e. enabled or disabled for all users (except for administrators).

MAY_UNREGISTER = False

DEFAULT_USER_LANG

The default user language is taken as default language for new users (or email addresses) in case no language is assigned explicitly.

Note

upon (self-)registration, the browser language is assigned to the new user.

DEFAULT_USER_LANG = 'en'

RESTRICT_MAIL

RESTRICT_EXT_MAIL

RESTRICT_SEND

A list (or tuple) of pairs (pattern, boolean) to restrict email addresses:

RESTRICT_MAIL restricts the set of email addresses that are accepted by BSCW for e.g. registration or invitation.

RESTRICT_EXT_MAIL restricts the set of external email addresses that are accepted by BSCW functions, such as appointment scheduling.

Note

RESTRICT_EXT_MAIL extends RESTRICT_MAIL patterns, i.o.w. RESTRICT_MAIL patterns are applied before patterns defined in RESTRICT_EXT_MAIL.

RESTRICT_SEND restricts the set of user email addresses that are allowed to send email via BSCW.

If the list is not empty, then a new mail address is translated to lower case and matched against the patterns (see Python module re). The boolean of the first matching pattern decides, if the mail address is accepted by BSCW. For example:
RESTRICT_MAIL = [('[^@]*@orbiteam.de', 1),]
restricts accepted email addresses to the single domain orbiteam.de.

Note

RESTRICT_* do not apply, if the inviting user is in the list of SERVER_ADMINS or USER_ADMINS.

RESTRICT_MAIL = ()
RESTRICT_EXT_MAIL = ()
RESTRICT_SEND = ()

MINPASSLEN

EXPPASS

EXPACCT

EXPACCT_ALERT

LOG_EXPIRED_USERS

BADPASS

CRYPT_HASH

User password quality and user account expiry settings

MINPASSLEN defines the minimal length of a users local password.
Note
A dictionary search to avoid the selection of weak passwords is available if the

cracklib (https://sourceforge.net/projects/cracklib/)

python3-cracklib package (https://www.nongnu.org/python-crack/)

are installed. To enable this feature set
MINPASSLEN = 'libcrack'
If MINPASSLEN == 'libcrack' cracklib may be configured using the PYTHONCRACK dictionary as follows:
PYTHONCRACK = {
    'MIN_LENGTH': 8,   # minimal password length
    'UP_CREDIT': -1,   # at least 1 upper case character
    'LOW_CREDIT': -1,  # at least 1 lower case character
    'DIG_CREDIT': -1,  # at least 1 digit character
    'OTH_CREDIT': -1,  # at least 1 other character
    'DIFF_OK': 3,      # min. difference old and new passwd
}
(see https://www.nongnu.org/python-crack/doc/crack-api.html)
EXPPASS defines the time interval users are required to change their passwords.

EXPACCT defines the time interval after which users are expired, if they did not login previously.

EXPACCT_ALERT specifies the time before a user is additionally notified by email about the upcoming expiration of the user account (requires activated expire package).

Possible values for the EXPPASS, EXPACCT or``EXPACCT_ALERT`` intervals may be specified in seconds or minutes (hours, days, weeks) with an additional 'm' ( 'h' , 'd' , 'w' ) suffix. E.g. valid values which specify one week are 604800 (or '604800'), '7d' or '1w'. A value of 0 disables enforced password changing resp. general user expiration or alert.

LOG_EXPIRED_USERS specifies the log file where all expired (and re-enabled) user accounts are logged.

BADPASS defines the number of failed authentication attempts after an user is locked. A value of 0 disables user password mismatch locking.

Note

The use is not advised, enabling this feature allows easy denial of service attacks.

CRYPT_HASH specifies the hash algorithm used when storing password hashes. Possible values for CRYPT_HASH are:

'sha512_crypt' to use SHA512 (default)

'sha256_crypt' to use SHA256

The following hash algorithms are for legacy support:

'md5_crypt' to use the Linux MD5 Modular Format (deprecated)

'des_crypt' to use DES (deprecated)

MINPASSLEN = 8
EXPPASS = 0
EXPACCT = 0
EXPACCT_ALERT = 0
LOG_EXPIRED_USERS = 'expired_users'
BADPASS = 10
CRYPT_HASH = 'sha512_crypt'

VIRUS_CHECK

SCANFILE

NO_VIRUSES_FOUND

VIRUS_FOUND

VIRUS_WAIT

VIRUS_DB_VERS

VIRUS_DB_CHECK

VIRUS_PASSWD

Settings for a virus scanner to scan files after upload or before download:

To enable a virus scan on download allows potential undetected viruses at upload time to be detected later with ongoing newer virus definitions of the virus scanner.

If a virus is found, the file will be quarantined in an encrypted ZIP archive with a predefined password (VIRUS_PASSWD).

The download virus scan is repeated every VIRUS_DB_CHECK seconds, if a new virus database version is detected (VIRUS_DB_VERS).

When enabling the virus scan feature the 7-Zip file archiver must be installed (Debian: p7zip-full, EL: p7zip)

VIRUS_CHECK defines in which situation files are scanned. Valid values are 0 (never), 1 (on upload) or 3 (on upload and download)

SCANFILE specifies the command string to scan a file. Use the pattern '%(file)s' for the file name. Consider in the parameters of the scan command to scan archive files (like ZIP) or emails. An empty value will deactivate the scanning.

NO_VIRUS_FOUND gives a list of result codes which the scan command will return if no virus is found.

VIRUS_FOUND gives a list of result codes which the scan command will return if a virus is found.

VIRUS_WAIT is the time (in seconds) the server will wait for a scan or quarantine process to complete before responding to a download request.

VIRUS_DB_VERS specifies the command string to get the version of virus database. If it is defined, a repetitive scan will not be done before the database has been updated.

VIRUS_DB_CHECK gives the interval (in seconds) between repetitive virus scans for a document (default: 86400 (1 day)). Within this interval, a document will not be re-scanned even if new virus definitions are available. The interval must be at least one hour.

VIRUS_PASSWD specifies the password that is used to protect access to a document that has been quarantined.

Example for Avast command line scan utility
SCANFILE = "/bin/scan -b '%(file)s'"
NO_VIRUS_FOUND = [0,]
VIRUS_FOUND = [1,]      # virus found
VIRUS_FOUND = [1, 2]    # virus found, avast error
VIRUS_DB_VERS = '/bin/scan -V'
To grant access to BSCW files add the avast system user to the bscw group, e.g:
$ su
# vigr
bscw:x:500:avast
Example for NAI McAffee VirusScan:
SCANFILE = "uvscan --mime --unzip '%(file)s'"
NO_VIRUS_FOUND = [0,]
VIRUS_FOUND = [13,]
Example for ClamAV:
SCANFILE = "/usr/bin/clamdscan --fdpass --no-summary '%(file)s'"
NO_VIRUS_FOUND = [0,]
VIRUS_FOUND = [1,]
VIRUS_FOUND = [1, 2]    # virus found, clamd error
VIRUS_DB_VERS = '/usr/bin/clamdscan -V'

VIRUS_CHECK = 0
SCANFILE = ''
NO_VIRUS_FOUND = []
VIRUS_FOUND = []
VIRUS_WAIT = 8
VIRUS_DB_VERS = ''
VIRUS_DB_CHECK = 86400
VIRUS_PASSWD = 'VIRUS'

4.2.4. web/proxy server settings¶

BSCW_REALM

HTTP Authentication parameter - as set in the Web server configuration.

Note

If you are running different BSCW servers on one host then you must use a different realm for each server.

BSCW_REALM = 'BSCW Social Workspace Server'

USE_HTTP_HOST

If not zero and the Host: header is sent by the client, then the BSCW server will use this header for generation of absolute server URLs.

Otherwise the URL will be taken from the SERVER_ROOT or from the environment variable SERVER_NAME or from the socket.gethostname() method (in this order).

USE_HTTP_HOST = 1

COOKIE_AUTHENTICATION

AUTH_MODE

OPEN_ID_DEFAULT

FEDERATIONS

By default BSCW authenticates user via HTTP cookies. This overrides the user authentication (perhaps already) done by the HTTP server. In order to avoid confusion, the HTTP server should not be configured to do authentication when COOKIE_AUTHENTICATION is enabled.

COOKIE_AUTHENTICATION is a triple (tagname, location, timeout)

with the following settings:
timeout = None      do not verify authentication tag (low security!)
timeout = 0         authentication tag does not expire
timeout = n         authentication tag expires after n minutes
location = None     use op_login for BSCW authentication
location = URL      jump to URL for authentication
e.g.:
COOKIE_AUTHENTICATION = ('bscw_auth', None, 120)
Cookie authentication is diabled with:
COOKIE_AUTHENTICATION = None
AUTH_MODE (authorization mode) specifies the authentication method BSCW uses when user credentials are passed to BSCW. AUTH_MODE must be

'Basic' for basic access authentication or

'Digest' for digest access authentication.

Warning

digest authentication is considered to be insecure. Better use https only with basic authentication.

Note

digest authentication is not possible in combination with ldap or with email address login. If you use one of these features AUTH_MODE must be 'Basic'

OPEN_ID_DEFAULT is set in order to enable OpenID registration and authentication (see https://openid.net/). For example, set:
OPEN_ID_DEFAULT = (
    "openid.net",
    "https://openid.net/get-an-openid/")
This will show a link to the “default provider” openid.net in the login page. This enables a user to get an OpenID URL if he does not have one. If you do not want to give a link to a default provider set:
OPEN_ID_DEFAULT = ("", "")
Note

COOKIE_AUTHENTICATION must be set and location (see above) must be None when OpenIDs are used.

Also the python3-openid package must be installed (https://github.com/openid/python-openid)

OpenID registration and authentication is disabled with:
OPEN_ID_DEFAULT = None
FEDERATIONS enables support for federation access and single-sign-on. This Feature works in conjunction with path prefixes for anonymous users defined in SCRIPTS (see below) and authentication modules provided for the Apache HTTP server (only mod_shib is currently supported).

FEDERATIONS must be the empty tuple () or a dictionary {}.
anonymous_user_name: (login_module, icon, restrict_mail)
For example, if you have defined a path prefix for the (anonymous) SnakeOilProviders '/pub/snakeoil/': ('SnakeOilProviders', ...) in the SCRIPTS dictionary, you can enforce Shibboleth authentication for accessing '/pub/snakeoil/' with the following entry in FEDERATIONS:
'SnakeOilProviders': ('login_shib', '<icon-url>', ()),
Parameters:

'login_shib' refers to the BSCW Shibboleth authentication module (the only one that is currently supported in this context).

BSCW uses the '<icon-url>' for a login-button button which is displayed in the login page. A user might click on it in order to authenticate via the federation.

the third parameter is a list of pairs (see RESTRICT_MAIL) that restrict the trusted email addresses for user identification and automatic registration via the federation. You might use () if you trust all authenticated email addresses.

the third parameter may also be set to RESTRICT_MAIL. In this case the normal RESTRICT_MAIL and MAY_REGISTER settings apply. Especially if no self-registration is allowed (MAY_REGISTER != []) then only invited users may auto-register via Shibboleth

Note

use bsadmin conf_apache and bsadmin index_page for (re-)configuration of the Apache HTTP server and the index page if you have changed COOKIE_AUTHENTICATION, SCRIPTS or FEDERATIONS.

test if authentication is correctly enforced by accessing <SERVER_ROOT>/pub/snakeoil/bscw.cgi/

COOKIE_AUTHENTICATION must be enabled to display the the login page in the first place.

this kind of login requires that the authentication process provides an authenticated email address of the user. For mod_shib this means that it must set the environment variable mail resp. HTTP_SHIB_INETORGPERSON_MAIL after successful authentication. To test open: <SERVER_ROOT>/pub/snakeoil/bscw.cgi/?op=env

See also

Section 5.13.3 Shibboleth Authentication for further configuration hints.

AUTH_MODE = 'Basic'
COOKIE_AUTHENTICATION = None
OPEN_ID_DEFAULT = None
FEDERATIONS = ()

COOKIE_AUTH_FORCE_LOGOUT

If COOKIE_AUTHENTICATION is enabled the authentication tag expires after the specified timeout. Certain operations (like presence bar, portal widgets and editor auto-save) will send automated requests in short intervals which keeps the user’s session alive.

If COOKIE_AUTH_FORCE_LOGOUT is enabled however, a session timeout is forced if no ‘real’ user interaction happens within the specified time.

COOKIE_AUTH_FORCE_LOGOUT = False

POST_AUTH

When enabled all POST requests must be authenticated by a hidden variable. To avoid cross-side attacks this must be enabled.

POST_AUTH = 1

POST_CHECK_REFERER

For POST requests the Referer header should start with the server root (of the BSCW web server). If this is not the case and when POST_CHECK_REFERER is True an error is raised.

Note

some proxies and browser might suppress the Referer header (they should not if the Referer URL is on the target host, since there is no privacy compromise in that case).

POST_CHECK_REFERER = 1

LOG_REG_USERS

LOG_REMOVED_USERS

If LOG_REG_USERS is not empty, all newly registered users at the system are logged in the file LOG_REG_USERS.

If not empty then all users that are removed from the system are logged in the file LOG_REMOVED_USERS. An entry is a line of the form:
user_name:user_id[:?]mail_address
An email address proceeded by '?' denotes an email address that was not owned by the user at the time of removal (hence the user has not received an email notification).

LOG_REG_USERS = 'registered_users'
LOG_REMOVED_USERS = 'removed_users'

PASSWD

PASSWD - Web server password file

If PASSWD is not empty the password file PASSWD is automatically managed by BSCW:
PASSWD = 'htpasswd'
Note

the web server password file is not used by BSCW any longer, but might be of interest for other web applications.

If you change the PASSWD file, you must also point your HTTP server to the new file.

See also

Section 3.4.1 Apache HTTP Server Configuration for Unix

PASSWD = ''

SCRIPTS

SECURE_SCRIPTS

CREATE_SCRIPTS

Define the CGI scripts that may be called the HTTP server. Given the URL https://bscw.domain.org/testing/sec/bscw.cgi/25, the HTTP server will split this URL into:

the SCRIPT_NAME "/testing/sec/bscw.cgi" and

the PATH_INFO "/25"

The BSCW server splits the script name further into :

the prefix "/testing/sec/" and

the script "bscw.cgi"

Note

the prefix always starts and ends with a /.

The BSCW accepts a SCRIPT_NAME, if the prefix is found in the SCRIPTS dictionary:
prefix: (username, '', create_scripts, extra_scripts)
The script is found in one of the two lists create_scripts or extra_scripts. If username is None, the user must authenticate. Otherwise the BSCW server assumes that the client may use the script without authentication (e.g. for anonymous access or access controlled by the client’s host domain). In the latter case the user will get access according to username.

Important

You have to apply for a new (“move server”) license if you have a granted BSCW license (not an evaluation license) and change the prefix for the entry with username None (the standard SCRIPTS prefix). See also SERVER_ROOT above.

Note

The usernames must be different in all tuples (username, ...) and there must exist at least a tuple with username None and a tuple with username anonymous.

The command bsadmin chkconfig needs the dictionary entry (which might be the same for all prefixes) in order to automatically create the scripts listed in create_scripts. For special purposes you might also create your own CGI scripts that eventually call the BSCW service. These scripts must be listed in extra_scripts.

The user objects for all usernames != None are automatically created and registered as anonymous users when the path prefix is accessed. If a non-anonymous user is found by username then the a "Bad script name" error will be raised.

The extra_script and SECURE_SCRIPTS feature is intended for experts only. CREATE_SCRIPTS is not used elsewhere. It is only defined for convenience.

SECURE_SCRIPTS = []
CREATE_SCRIPTS = ['bscw.cgi']
SECURE_PREFIX = '/sec/'
PUBLIC_PREFIX = '/pub/'
SCRIPTS = {
    SECURE_PREFIX: (None, '', CREATE_SCRIPTS, SECURE_SCRIPTS),
    PUBLIC_PREFIX: ('anonymous', '', CREATE_SCRIPTS, SECURE_SCRIPTS),
    # '/pub/snakeoil/':
    #     ('SnakeOilProviders', '', CREATE_SCRIPTS, SECURE_SCRIPTS),
}

SILENT_ERROR_FOR
If a script prefix is listed in SILENT_ERROR_FOR, any error message will be replaced by SILENT_ERROR.html which then must reside in the directory bscw/templates of the server. For example:
SILENT_ERROR_FOR = (PUBLIC_PREFIX,)
will prevent error related information from being collected by misuse of public access.

SILENT_ERROR_FOR = (PUBLIC_PREFIX,)

SCRIPTS_OTHER_ROOTS

If you have more than one BSCW server instance on a single host, you must select one of them to handle all document root / WebDAV PROPFIND requests for all BSCW server instances on this host. E.g. if you have another BSCW server that handles requests on /bscw1 and /pub1 (see SCRIPTS above), you might set
SCRIPTS_OTHER_ROOTS = ('/bscw1', '/pub1')       on this server and
SCRIPTS_OTHER_ROOTS = None                      on the other server.
Note

You have to re-generate the Apache configuration with with bsadmin conf_apache when you make changes to SCRIPTS or SCRIPTS_OTHER_ROOTS and restart the web server.

SCRIPTS_OTHER_ROOTS = ()

SSO_PREFIX

SSO_SCRIPT

CAS_URI

SCRIPTS_ALIASES

To enable Single Sign On support for the Central Authentication System (CAS; https://www.apereo.org/programs/software/cas/) an alternate secure path prefix SSO_PREFIX, an CAS service URL CAS_URI and an alternate secure script path (SCRIPTS_ALIASES) must be defined.

SSO_PREFIX defines a path prefix which is redirected to the SSO authentication service. If undefined or empty SSO support is disabled (default).

SSO_SCRIPT (optional) defines an additional alternate script name of the CGI script which is redirected to the SSO authentication service. If undefined or empty CREATE_SCRIPTS[0] is used (default).

CAS_URI defines the URL of the CAS Single Sign On service, e.g.:
CAS_URI = 'https://sso.domain.org:8080/cas'
SCRIPTS_ALIASES define alternate script alias prefix paths for the secure prefix:
SCRIPTS_ALIASES = {
    SECURE_PREFIX: [
        (SSO_PREFIX, {
            'mode': AUTH_MODE,
            'cookie': ('bscw_cas', None, 120) }), ],
}
A script alias prefix path definition is a list of tuples [('path_alias', auth_dict)]. For every script alias prefix path the authentication dictionary auth_dict defines the authentication mode and (if needed) cookie authentication, e.g.:
auth_dict = {'mode': 'Digest', 'cookie': None}
auth_dict = {'mode': 'Basic',
    'cookie': ('bscw_cas', None, 120)}
For available mode values see the AUTH_MODE and for available cookie values see the COOKIE_AUTHENTICATION configuration directives above

CAS_URI = ''
SSO_PREFIX = ''
SSO_COOKIE = ('bscw_cas', None, 120)
SCRIPTS_ALIASES = {
    SECURE_PREFIX: [
    (SSO_PREFIX, { 'mode': AUTH_MODE, 'cookie': SSO_COOKIE }), ],
}

PATH_INFO_SLASH

Must have the values '' or '%2f' or '%2F'. This should only be set not empty if the Apache HTTP server is used and AllowEncodedSlashes On is set. It must be equal to the encoding that the Apache HTTP server uses for URI path segments ('%2f').

Warning

This is an experimental feature. Many DAV clients do not work with encoded slashes in URI path segments. Better leave it empty by now.

PATH_INFO_SLASH = ''

SERV_DOWNLOADS

allows the BSCW server to download resources from external sites (e.g. to generate thumbnails for links). By default SERV_DOWNLOADS is set to True. Disable this feature if the BSCW server is located in a DMZ.

SERV_DOWNLOADS = True

HTTP_PROXY

HTTPS_PROXY

FTP_PROXY

Specify proxies for various server types (i.e. http, https, ftp) by defining a variable named <TYPE>_PROXY. This variable denotes the proxy server for this type by the form <scheme>:://<name>:<port>. For example
HTTP_PROXY = 'http://proxy.orbiteam.de:3128'
HTTPS_PROXY = 'https://sslproxy.orbiteam.de:3128'
FTP_PROXY = 'proxy.orbiteam.de:3128'
The proxies are used by the BSCW server if it fetches or verifies an URL.

HTTP_PROXY = ''
HTTPS_PROXY = ''
FTP_PROXY = ''

BYPASS_PROXY

Gives a list for domains, where the proxy should be bypassed, i. e., a host whose end of its name matches one of the domains, will be connected directly. Normally it should be set to the local domain. For example:
BYPASS_PROXY = ['fit.fraunhofer.de', 'orbiteam.de']

BYPASS_PROXY = []

FTP_GATEWAY

Sets a FTP firewall gateway IP address (or hostname) for the export operation.

FTP_GATEWAY = ''

EDITOR_SETTINGS

EDITOR_SETTINGS defines the settings for the built-in HTML (TinyMCE) editor:

'code_sample' toggles source code formatting

EDITOR_SETTINGS = {
    'code_sample': True,    # enable formatting of source code
}

GET_MIME_TYPES_AS_ATTACHMENT

You may want to configure the system to get/open certain document types (i.e. MIME Types) as attachments and not directly within the browser (which is the default behaviour when users click on a link). Especially for newer versions of Microsoft Office, attachments can avoid strange effects and frustrating user experience: Links to MS-Office documents (Word, Excel, Powerpoint…) will usually let MS-Office open the document directly from the BSCW server and so ask for username / password, even though the document is opened read-only (i.e. for reading or printing only) and the ‘save to server’ feature is not available. As a workaround, MS suggests to explicitly mark the content as a read-only download (i.e., as an “attachment”). In that case, the browser will download the document with the known login information and afterward open MS-Office on the downloaded file.

See also

https://support.microsoft.com/kb/899927/en-us

For all document types configured below, BSCW will add the Content-Disposition: Attachment header to the response whenever the user clicks a link to the document in a container page.

GET_MIME_TYPES_AS_ATTACHMENT = (
 'application/vnd.ms-excel',
 'application/vnd.ms-project',
 'application/vnd.ms-powerpoint',
 'application/vnd.ms-word',
 'application/vnd.visio',
 'application/rtf',
 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
 'application/vnd.ms-excel.sheet.macroenabled.12',
 'application/vnd.openxmlformats-officedocument.presentationml.presentation',
 'application/vnd.ms-powerpoint.presentation.macroenabled.12',
 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
 'application/vnd.ms-word.document.macroenabled.12',
)

4.2.5. BSCW appearance settings¶

USER_SEARCH_LIMIT

Maximum number of matching hits by a User Search

USER_SEARCH_LIMIT = 100

MEMBER_SEARCH

Defines, if the search for BSCW users, is allowed on the add member form

MEMBER_SEARCH = 1

MAX_VERSIONS

MAX_VERSIONS_KEEP

MAX_VERSIONS_LIMIT

Controls the autoversion behavior for newly created documents:

If MAX_VERSIONS is

1 (default), new created documents are not set under version control.

0, new created documents are automatically set under version control and all revised versions will be stored.

<n>, new created documents are automatically set under version control, but only the latest <n> revised versions will be stored.

Revising version <n>+1 will automatically remove the oldest revision.

If the MAX_VERSIONS_KEEP list is not empty, all version ids of a document are matched against the RE patterns. The boolean of the first matching pattern decides if a version id gets removed when MAX_VERSIONS is set to store the latest <n> revised versions.

For example:
MAX_VERSIONS_KEEP = [
    ('.*\.0$', True),
]
will avoid the removal of all version ids ending with “.0”

If MAX_VERSIONS_LIMIT is set to a value > 1, the maximum number of user configurable version revisions (cf. [> Change > Properties] form) is limited to MAX_VERSIONS_LIMIT.

Note

This does not affect the global setting (cf. MAX_VERSIONS)

When defining MAX_VERSIONS_LIMIT, MAX_VERSIONS must be equal or less MAX_VERSIONS_LIMIT and unequal 0.

MAX_VERSIONS = 1
MAX_VERSIONS_KEEP = []
MAX_VERSIONS_LIMIT = 0

GRID_BROWSER_LIMIT

When all entries of a folders’ contents grid are loaded at once, the grid can do certain things locally without additional server requests, like fast scrolling or sorting entries. In large folders, however, it is not advisable to load all entries at once to avoid exceptional memory consumption of client browsers.

GRID_BROWSER_LIMIT = 450

GRID_PAGE_SIZE

The number of entries that folder’s contents grids fetch at once. A larger number means less server requests, but longer load times per server request. Should never exceed GRID_BROWSER_LIMIT

GRID_PAGE_SIZE = 150

SCRIPT_POLL_INTERVAL

This is the time interval in which the JavaScript components will reload their contents. The value is set in seconds. So by default e.g. the contacts view will reload its contents every 60 seconds, and new microblog posts will pop up each 60 seconds.

SCRIPT_POLL_INTERVAL = 60

EDITOR

Mime type for BSCW uploading and edit helper. On client side, this Mime type should be configured to one of our BSCW uploader and generic editor programs:
EDITOR = 'application/x-bscw-edit'
The user must have an application (i.e. script) bound to this mime type and should have selected “external editors” (in the [Menu ‣ Preferences] [File Handling] menu). Upon “edit” action, BSCW serves a file that contains four lines:

the URL, where the file can be downloaded (GET) or uploaded (PUT)

the mime type of the file

the encoding of the file

the name of the file
EDITOR = 'application/x-zope-edit'
The Zope External Editor is used for editing cycle, i.e. upon “edit” action, BSCW serves a file with according mime type and content (as expected by Zope External Editor). The user must have the Zope External Editor installed and should have selected some “external editors” (in the [Menu ‣ Preferences] [General] [File Handling] menu).

EDITOR = 'application/x-zope-edit'

ConversionMethode

Parameter for file conversion: all possible conversions for a file should be shown (0) or only the best one (1).

ConversionMethode = 1

THEMES

Available themes to be chosen by users. Every theme is based on a config_theme.py, which contains values for placeholders. The final .css files are then generated using bsadmin themes. Names for own themes can be defined in language files with the key theme_<MY THEME>, e.g. theme_default, theme_default_dark

THEMES = (
    'default/default',
    'default/default_dark',
)

SOUND_THEMES

Available sound themes to be chosen by users. Every theme added over here should contain the same audio files as defined in file:sounds/bscwSounds. Names for own themes can be defined in language files with the key audio_theme_<MY THEME>, e.g. audio_theme_bscwSounds

SOUND_THEMES = [
   'bscwSounds',
]

RATE_COLORS

Colors for URL ratings: [ 'none', 'poor', 'passable', 'fair', 'good', 'excellent']

RATE_COLORS = [
    '#000000', '#404878', '#6068a0',
    '#7680d0', '#ff8000', '#ff0000']

AVATAR_COLORS

A list of colors with tuples of (background_color, font_color) for auto-generated user avatars (if user doesn’t provide a photo) Note: this feature requires GraphicsMagick: https://www.graphicsmagick.org

Both color names or hex values (e.g. ‘white’ or ‘#ffffff’) can be used - as supported by GraphicsMagick: https://www.graphicsmagick.org/color.html

AVATAR_COLORS = [
    ('#004F80', '#FFFFFF'),  # dark blue 100%
    ('#00B8F2', '#000000'),  # light blue 100%
    ('#74B917', '#000000'),  # light green 100%
    ('#0778A5', '#FFFFFF'),  # blue 100%
    ('#FFC819', '#000000'),  # yellow 100%
    ('#F28502', '#000000'),  # orange 100%
    ('#C40046', '#FFFFFF'),  # red 100%
    ('#6B7581', '#FFFFFF'),  # gray 100%
    ('#890D48', '#FFFFFF'),  # dark red 100%
    ('#23614E', '#FFFFFF'),  # dark green 100%
]

REFTYPES

DOTDIR

REFTYPES is a list of MIME Types of documents that may contain URLs with relative anchors, especially ../-references. If a web browser resolves such ../-references it removes elements at the end of the documents URL path. Hence a sufficient number of (dummy DOTDIR) directories must be inserted into the document’s URL.

Note

DOTDIR must contain exactly one / and it must be the last character.

REFTYPES = ['text/html']
DOTDIR = '*/'

HIDE_PUBLIC_SPACE

HIDE_PUBLIC_SPACE defines the visibility of the public space. By default, the content of the public folder is hidden (HIDE_PUBLIC_SPACE = True). If HIDE_PUBLIC_SPACE is set to False, the public folder content is generally visible.

HIDE_PUBLIC_SPACE = True

ANONYMOUS_SEARCH

allow searching for anonymous user.

ANONYMOUS_SEARCH = True

LOCAL_URL_PREFIX

It is possible (for administrators only) to make URL links into the local file system. If LOCAL_URL_PREFIX is 1 and the URL has the form local:<local file path> then the file or directory on the local file system is accessed by the GET operation on the URL (a relative local file path is interpreted relative to the runtime directory). If the directory contains a file named index.html (recommended!) the contents of index.html are returned instead of a directory listing.

Example: set LOCAL_URL_PREFIX = 1 and add (as admin) a URL named local:var/log/sys.log to a workspace to provide access to your <bscw-runtime-path>/var/log/sys.log.

Note

A user, not being administrator, cannot create a local:... URL, even if LOCAL_URL_PREFIX is not (yet) enabled. A leading slash will be interpreted as an absolute file path. I.e. the URL local:/etc/passwd will result in access to the file /etc/passwd on the server.

this feature is experimental, and has obvious security implications! It is disabled by default.

LOCAL_URL_PREFIX = 0

SYS_MSG

Display system messages. SYS_MSG denotes the number of last system message. If SYS_MSG > 0, you must have files
sys_msg1.html, sys_msg2.html ... sys_msg<SYS_MSG>.html
in conf/msg/en/ (and optional the corresponding translated files in other language dependant directories conf/msg/<lang>/). All files must be encoded in UTF-8. See conf/msg/en/sys_msg1.html as an example. The files are displayed to users as system messages and must be confirmed.

Note

Newly registered users will see sys_msg0.html (if provided).

SYS_MSG = 0

SYS_BUSY

Set, if the server is unavailable for processing requests. The message in file conf/msg/en/<SYS_BUSY>.html will be returned. (See conf/msg/en/sys_busy.html as an example)

Note

the path and the filename ending .html is appended to SYS_BUSY.

SYS_BUSY = ''

INDEX_MSG

Display a custom welcome message on the index page. Here important messages (e.g. terms of use of the server) can be linked/announced. The string may include HTML code, e.g.:
INDEX_MSG = '<h3>Efficient collaboration service.</h3>'
Note

you need to run bsadmin index_page in order to update the index page

you may also define language dependant welcome messages for DE, FR etc. by defining INDEX_MSG_DE, INDEX_MSG_FR etc. (INDEX_MSG should be default/EN)

INDEX_MSG = ''

INDEX_PAGE_EXTRA_CONTENTS

Define some folder id in here, where some extra contents for your index page are defined. Inside this folder you can add the following stuff.

Define sub folders with files like (de.html, en.html, …) that will be added as sub sites in your index page navigation bar.

By default the folder name is used as page title in navigation bar. You can change the displayed name by setting some description for each individual html file.

By adding some html file (de.html, en.html, …) into your folder you can define some extra html message that is placed below the displayed login field.

Note

CSS from HTML file headers will be ignored. Just use the theme’s style.less file to add styles. Then rebuild your CSS and your index page. Besides, you can use inline styles.

So add some ID in here:
INDEX_PAGE_EXTRA_CONTENTS = 1234
The folder with the id 1234 could look like this:
My Folder (with ID 1234) has the following contents:
|1_Subpage
|- de.html
|- en.html
|
|2_Subpage             (also note: links will be sorted by
|- de.html              name. To add some order just add some
|- en.html              leading 1_, 2_, 3_, ... to your filename)
|
|de.html
|en.html
Note

Everytime after you have made changes inside your folder, you have to run “bsadmin index_page” once again.

INDEX_PAGE_EXTRA_CONTENTS = 0

SERVER_HOME

SERVER_HELP

SERVER_INFO

SERVER_CANCEL

SERVER_LOGOUT

Locations of various resources for the URLs in the BSCW Banner.
SERVER_HOME - BSCW server home page
SERVER_HELP - BSCW Help files (English)

SERVER_HELP_DE - BSCW Help files (German)

SERVER_HELP_FR - BSCW Help files (French)

by default the help is served from local BSCW server, alternatively you may use the publicly available help:
SERVER_HELP = 'https://www.bscw.de/en/social/help'
SERVER_HELP_DE = 'https://www.bscw.de/social/help'
SERVER_INFO - BSCW server info page - by default it shows the index page in the scripts directory for anonymous (see SCRIPTS).

SERVER_CANCEL - Defines an URL, to which will be redirected if cancel is pressed (currently chpwd and rmail). Default is SERVER_INFO.

SERVER_LOGOUT - Defines an URL, to which will be redirected after logout (currently for COOKIE_AUTHENTICATION only). Default is SERVER_INFO.

SERVER_HOME = '/'
SERVER_HELP = ''    # local help
SERVER_HELP_DE = '' # local help
SERVER_HELP_FR = '' # local help
SERVER_INFO = SERVER_HOME
SERVER_CANCEL = SERVER_HOME
SERVER_LOGOUT = SERVER_HOME

SERVER_TIMEZONE

Should be set to the time zone that corresponds to time.localtime and should be given in the form “Continent/City”. If you are not sure, use the special value “localtime”.

SERVER_TIMEZONE = 'localtime'

BSCW_LICENSE

URL used for requesting BSCW license upgrades. This should not be changed.

BSCW_LICENSE = 'https://license.bscw.de/pub/bscw.cgi/'

FMT_DISTINCT_NAME

A pattern format to build a distinct name from the favoured name, an extension and a number. The format must take name and extension as positional arguments and the number as keyword ‘number’.

Examples:
'{}~{number}{}'.format('Manual', '.pdf', number=2)   => Manual~2.pdf
'{} ({number}){}'.format('README', '.txt', number=2) => README (2).txt
'{} ({number}){}'.format('folder', '', number=2)     => folder (2)
The special value None will disable the feature:
FMT_DISTINCT_NAME = None

FMT_DISTINCT_NAME = None

BSCW_UI_NAME

Which name should be displayed at HTML user interface.

favoured name
favoured name, add extension
favoured name, strip extension
distinct name
distinct name, add extension
distinct name, strip extension

BSCW_UI_NAME = 0

4.2.6. Optional BSCW packages¶

PACKAGES

A list of directories containing BSCW extension packages. List of available packages:

'approval',             # Document Approval
'chat',                 # Chat
'expire',               # User account expiration
'exportpdf',            # Export views to PDF (requires reportlab)
'FlowFolder',           # Flow Folder
'http',                 # pre-forking BSCW HTTP server
'incognito',            # support anonymised read access
'ldap',                 # LDAP interface
'metaprofiles',         # User-defined metadata profiles
'office',               # Online Office
'poll',                 # Opinion polls and schedules
'PyLucIndex',           # Pylucene Indexer
'task',                 # Task Management
'WebFolder',            # Web Folder

Attention

The PACKAGES list is maintained by the bsadmin package command. Do not manually edit the PACKAGES list.

To enable a package run

bsadmin package -e <pkg-name>

bsadmin package -e ldap

To disable a package run

bsadmin package -d <pkg-name>

bsadmin package -d ldap

PACKAGES = [
    'approval',         # Document Approval
    'chat',             # Chat
    'FlowFolder',       # Flow Folder
    'poll',             # Poll, Schedule, Appointment Scheduling
    'task',             # Task Management
    'WebFolder',        # Web Folder
]

SERV_UNO_STATE

SERV_UNO_TIMES

WSREPORT

WSREPORT_DIRECT

AUTOSUBSCRIBE_REPORT

AUTOSUBSCRIBE_REPORT_DIRECT

DEFAULT_EVENTMASK

DEFAULT_EVENTMASK_DIRECT

WSREPORT_EVENT_LIMIT

REPORTLOG

The user notification services (UNO) perform the following tasks:

sending periodical workspace activity reports via email to give the users an overview about recent activities in a specific time period (e.g. daily)

sending direct email notifications to inform the users instantly about recent events (optional)

Using the user notification services a BSCW user does not need to contact its BSCW server(s) so often to check for new events. If the user notification services are activated, the users’ event preference page provides a column for subscription of the “Periodic Report” or the “Direct Email” notification (depending on the UNO service configuration).

By default a daily report is sent to new users, but each user may decide to unsubscribe from the workspace report by himself. The server administrator can change this behavior using the AUTOSUBSCRIBE_REPORT = 1 flag. If this is enabled new users will automatically be subscribed to the user notification service.

Accordingly the direct email notification is enabled by default for each user so each user may decide to disable the direct email. The server administrator can change this behavior using the AUTOSUBSCRIBE_REPORT_DIRECT = 1 flag. (Again this affects all new users and those users who have not yet changed their event preferences.)

To activate the user notification service the BSCW administrator has to start an additional UNO server (bscw.adm.bs_servuno). See section SERVERS for details on how to start bscw.adm.bs_servuno.

Note

UNO accesses the BSCW database server via an extra (virtual) HTTP server running on http://localhost:<HTTP_LOCAL_PORT>. See HTTP_LOCAL_PORT for details.

Also, the following variables have to be set for configuration of bscw.adm.bs_servuno:
SERV_UNO_STATE: A file name for saving the state of the bscw.adm.bs_servuno service must be given here. The file is written, when the bscw.adm.bs_servuno is stopped and read when the server is started again.

SERV_UNO_TIMES: A dictionary containing fine tuning parameters for bscw.adm.bs_servuno; if is set to SERV_UNO_TIMES = None the default settings are used (as shown below). To overwrite the default settings for fine tuning parameters use e.g.:
SERV_UNO_TIMES = {
    'TdelayDirect': 60.,
    'MaxRetry': 20,
}
The defaults are:

'TdelayDirect': 60.: Delay direct notification one minute for the first affected user. This is to accumulate more events in the direct notification mail.

'TdelayNextProc': 3.: Add a delay of 3 seconds for the next affected user. This is to avoid an overload of the mail server if a lot of users are affected,

'TdelayNextDirect': 300.: Delay the next direct notification for the same user five minutes. This is to avoid an overload of the user.

'TdelayDaily': 5.: Add a delay of five seconds between daily notification mails. This is to avoid an overload of the mail server if the service has to send the notification to a lot of users.

'TdelayRetry': 600.: Add a delay of 10 minutes after the notification has failed and retry then.

'MaxRetry': 2: 2 retries that are delayed with TdelayRetry.

'TdelayFailed': 21600.: After MaxRetry the notification is delayed 6 hours (0 may be assigned here, then there will be no retry upto next midnight).

'FailMessagesAt': 10: Log an error message every 10th failure (first, 11th, 21st …) Note: No error messages are logged after MaxRetry (special values 1: each message 0: never)

'MaxJobs': 4: Maximum number of parallel running mail processes. This will also determine the load of the BSCW server and the mailer. Note: For more throughput on big server machines this value might be increased.

'QueueInfo': 20: Show job queue status after 20 jobs are queued (use values: 2^n * MaxJobs)

'ReportTime': 01:31: Start daily/weekly reports at 01:31 (must be >= 00:00 and < 07:00)

'WeekReportDay': '7': Weekly reports on Sunday (must be >=1 [Monday] and <=7 [Sunday])

WSREPORT = 1 (0) enable (disable) the periodic (daily/weekly) report.

WSREPORT_DIRECT = 1 (0) enable (disable) the direct email report.

Note

When bscw.adm.bs_servuno does not run the periodic report and the direct email report are disabled. Whenever the values of WSREPORT or WSREPORT_DIRECT are altered bscw.adm.bs_servuno must be restarted to take these changes into effect.

AUTOSUBSCRIBE_REPORT defines the periodic report default subscription for all users AUTOSUBSCRIBE_REPORT_DIRECT defines the direct email report default subscription for all users.

Note

Once a user has changed its subscription preferences this flag will have no further effect - but the administrator may use the bsadmin report command to change a user’s report subscription later).

DEFAULT_EVENTMASK defines the event type subscription mask for most of the awareness services (like periodic report or external services), with the values
read = 1; create = 2; move = 4; change = 8
By default all event types are subscribed, except of read events. (create + move + change = 14)

DEFAULT_EVENTMASK_DIRECT defines the default event type subscription mask for the direct email notification. By default no event types are preselected, so users won’t be notified about any events immediately, but may select some event types for certain folders of interest only.

DEFAULT_EVENT_REPORT_DAILY defines the default frequency for periodic email report which may either be daily (1) or weekly (0)

For example, set
WSREPORT_DIRECT = 1
AUTOSUBSCRIBE_REPORT_DIRECT = 1
DEFAULT_EVENTMASK_DIRECT = 2
to enable the direct email notification service for all users by default, so each user will receive an email for each newly created object! (We do not recommend this setting though.)

WSREPORT_EVENT_LIMIT defines a size limit of the periodic workspace report: in order to prevent too long notification emails the number of events can be limited (use WSREPORT_EVENT_LIMIT = 0 for unlimited size)

REPORTLOG points to a file in which a protocol about the reports is logged. For example:
REPORTLOG = 'report.log'

SERV_UNO_STATE = 'ServUnoState'
SERV_UNO_TIMES = None
WSREPORT = 1
WSREPORT_DIRECT = 1
AUTOSUBSCRIBE_REPORT = 1
AUTOSUBSCRIBE_REPORT_DIRECT = 1
DEFAULT_EVENTMASK = 14
DEFAULT_EVENTMASK_DIRECT = 0
DEFAULT_EVENT_REPORT_DAILY = 1
WSREPORT_EVENT_LIMIT = 500
REPORTLOG = ''

ALWAYS_CREATE_READEVENTS

CREATE_READEVENTS_OPTION

BSCW Awareness Service configuration

Setting ALWAYS_CREATE_READEVENTS > 0 enables the creation of read events, even if a user has already read the document and the document was not modified in between. This is sometimes needed for enhanced awareness.

Setting ALWAYS_CREATE_READEVENTS = 0 creates read events, after the first time a user reads a (unchanged) document. For successive reads no further read event is created (default).

Setting ALWAYS_CREATE_READEVENTS < 0 suppresses generation of read events.

Setting CREATE_READEVENTS_OPTION = 1 enables the manager of a workspace (respectively folder) to define (for this context) if read events should be tracked or not. If no option is defined, the setting is inherited from the parent folder. If no option is defined on any parent folder, the default option (i.e. ALWAYS_CREATE_READEVENTS) is used.

ALWAYS_CREATE_READEVENT = 0
CREATE_READEVENTS_OPTION = 0

SERVERS

The SERVERS list is used for starting (and stopping) BSCW servers. Only extra server addresses and implementation modules should be specified here (GSERV, SERV_ALARM, SERV_ACCESS are defined below). The extra servers are specified by a pair (address, module) or a triple (address, service_module, protocol_module). The default protocol_module is 'bscw.core.cl_servublk'. The following RPC protocol modules are available:
bscw.core.cl_servublk

standard rpc module, can be used with either a file path (recommended) or a (host, port) TCP/IP address. In the first case the module uses a unix socket if possible or selects a free port for a local IP connection and stores it in the given file.

bscw.core.cl_servinet_ext

for non Python services, (host, port) addresses only.

Example for starting the user notification server:
SERVERS = [
    ('UnoSocket','bscw.adm.bs_servuno'),
]

SERVERS = []

4.2.7. BSCW database server settings¶

STORE

STORE_PAIR

TABLES

CLEAN

SAVE

Persistent object store and garbage collection. Relative paths are relative to the BSCW database directory (<bscw-runtime-path>/var/data)

STORE

Normally contains actual sizes of files in STORE_PAIR and a garbage collection (GC) counter. Only for disaster recovery, put a backup into this file and start the server.

STORE_PAIR

The BSCW database server uses one of the files in this pair as the current StoreFile. The other one is free for garbage collection (called the GcFile). These files contain data of all persistent objects and will grow big. The database server only appends data to the the current store file. So it must be garbage collected from time to time (every day is recommended!). The garbage collector copies actual data from store file to GC file and then swaps the files.

TABLES

BSCW database table information used for fast database server restart.

CLEAN

Prefix for some temporary files during garbage collection. The database server moves STORE to CLEAN during initialization.

SAVE

For the purpose of backup, the garbage collector copies the new current StoreFile to this file just before it finishes.

Note

bsadmin getconfig STORE shows the current store file from STORE_PAIR

It is strongly recommended that STORE, TABLES and CLEAN are in the same directory and the (base) file names are not changed. For increased reliability, put SAVE and the files in STORE_PAIR on different devices. Never put STORE, TABLES, CLEAN and the files in STORE_PAIR on a shared file system.

On Unix systems, STORE_PAIR may also point to (properly configured) block devices e.g. STORE_PAIR = ('/dev/sdb3', '/dev/sdb4').

STORE = 'Store'
STORE_PAIR = ('StoreA', 'StoreB')
TABLES = 'Tables'
CLEAN = 'Garbage'
SAVE = 'Backup'

ALARM_DIR

FILES

TEMP

Persistent alarm store, file store and temporary files. Relative paths are relative to the BSCW database directory (<bscw-runtimepath>/var/data)

ALARM_DIR: Directory for scheduled alarms

FILES: Root directory of document file tree

TEMP: Directory for temporary files

We recommend that the directories TEMP and FILES are on the same file system. In this case only a link (instead of a copy) is necessary to put a temporary file in the right place, e.g. after document upload.

Note

You can find the file for a BSCW Document with id 12345 at <FILES>/01/23/45F, probably with some extension .xxx depending on the file type.

ALARM_DIR = 'Alarm'
FILES = 'Files'
TEMP = 'Temp'

FILES_SWITCH

Simulates “soft links” in the BSCW file store. A list (or tuple) of pairs (path-pattern, substitute) determines the actual location of a BSCW file. E.g. if
FILES = '/media/nas/Files'
(see below), then
FILES_SWITCH = (('/media/nas/Files/01', '/media/nas2/Files/01'))
will substitute all BSCW file paths starting with /media/nas/Files/01 by file paths starting with /media/nas2/Files/01. This may be used for distributing the BSCW file store on different disks etc.

Note

Some bsadmin tools like bsadmin fsck do not support this feature and may give wrong results.

FILES_SWITCH = ()

RMUSER_DIR

RMUSR_ARC

RMUSR_VER

RMUSR_ENC

Archive configuration for (optional) archiving of removed user artifacts:

RMUSR_DIR - directory for archives of removed users

RMUSR_ARC - format for removed users archives: 'zip' (default) or 'tar'

RMUSR_VER - archive all versions of a document: True (default) or False

RMUSR_ENC - pathname encoding: 'UTF-8' (default)

RMUSR_DIR = 'rmuserarc'

SERV_ACCESS

SERV_ACCESS_STATE

SERV_ACCESS specifies the address of the access server bscw.adm.bs_servaccess. The bscw.adm.bs_servaccess service is an optional accelerator for searches. It implements fast access filtering. Disabled if empty.

In order to enable this service use SERV_ACCESS = 'AccessSocket'
Note

If you enable this service on an upgraded Server you might get an error (e.g. in bscw.log) like:
mm-dd hh:mm:ss ACCESS watch died:
RuntimeError: Old pickle not supported
In this case
$ bin/bsadmin garbage bs_classtabe0
$ rm var/data/ServAccessState
$ bin/bsadmin start
will solve the problem. In the case of
mm-dd hh:mm:ss ACCESS position nnnnn:
ValueError: bad marshal data
a clean restart without reading the saved state might help:
$ rm var/data/ServAccessState
$ bin/bsadmin start
SERV_ACCESS_STATE - File to save state of bscw.adm.bs_servaccess when the access server is shut down. This file is only used when bscw.adm.bs_servaccess is enabled.

SERV_ACCESS = ''
SERV_ACCESS_STATE = 'ServAccessState'

SERVER_LOG

BSCW_LOG

All requests to BSCW are logged in this file. Should be set for analyzing purposes only. A log entry contains the following information (divided by blanks):

request date (local time)

remote host

remote user

request method

BSCW operation

response code

request duration (CPU time)

request duration (real time)

request path

Server activities (e.g. start, stop, gc) and errors will logged in BSCW_LOG.

SERVER_LOG = 'server.log'
BSCW_LOG = 'bscw.log'

BSCW_UMASK

BSCW_UMASK restricts access to owner and group by default (i.e. mask out read, write and execute bits for “other” users). This mask is used only on UNIX systems.

BSCW_UMASK = 7

DBMOD_TAB

DBMOD_CACHESIZE

DBMOD_PAGESIZE

DBMOD_HASH

DBMOD_MINKEY

DBMOD_TAB: definition of the BSCW database table type:

the default value 'dict' uses Python dictionaries and should be used for small BSCW databases only, because the key and offset tables are hold in memory of the bs_servdb process and must be loaded to memory and stored to disk on server start and shutdown respectively.

the value 'bsddb4' uses an external Berkeley DB to store the BSCW database tables and requires an installed Berkeley DB (https://www.oracle.com/database/berkeley-db) and the additional bsddb module. Python 3 requires the installation of the bsddb3 module (python3-bsddb3)

The following configuration parameters DBMOD_CACHESIZE, DBMOD_PAGESIZE, DBMOD_HASH, DBMOD_MINKEY are only used with DBMOD_TAB = 'bsddb4':

DBMOD_CACHESIZE: defines the cache size of the Berkeley DB. The recommended cache size is about 10-15% of the actual STORE size.

Note

DBMOD_CACHESIZE < 100 defines cache size in giga bytes (GB) DBMOD_CACHESIZE >= 100 define cache size in bytes (B)

DBMOD_PAGESIZE: specifies the size of a single cache page. Do not choose too big values to avoid high I/O load (default: 8192)

DBMOD_HASH: uses Berkley DB HASH access method (instead of the default BTREE access method).

Note

This option is not recommended!

DBMOD_MINKEY: is a pair of two values which are only used with the BTREE access method (the default). The values depend on the maximum key + data size of the offset table (StoreOff) and the key table (StoreKey) respectively. The values should be less than:

DBMOD_PAGEZIZE / 2*<max key+data size>

A good working heuristic value pair seems to be:
DBMOD_MINKEY = (9*(DBMOD_PAGEZIZE/1024), 5*(DBMOD_PAGEZIZE/1024))

DBMOD_TAB = 'dict'              # Python dictionary (default)
DBMOD_CACHESIZE = 2097152       # cache size in bytes
DBMOD_PAGESIZE = 8192           # page size in bytes
DBMOD_MINKEY = 72, 40           # heuristic values for page size 8192

GSERV

SERV_ALARM

GSERV - address of database server socket DBMOD

SERV_ALARM - address of alarm server socket (bscw.adm.bs_servalarm)

Filenames are recommended here. Fixed local port addresses like ('localhost', 12966) should only be used if there are problems with UNIX sockets or the automatic TCP/IP port selection does not work.

The bscw.adm.bs_servalarm service schedules alarms for persistent objects.

GSERV = 'DbSocket'
SERV_ALARM = 'AlarmSocket'

XDPROXY_ENABLED

XDPROXY_TRANSFORMATIONS

XDPROXY_URLS

BSCW can act as a proxy for “cross-domain requests”, required for some AJAX features like used in the portal. This proxy requires authentication and is thus only open to your BSCW users. You can turn the proxy on and off using XDPROXY_ENABLED. The proxy will refuse to download any URL that does not match any regular expression in XDPROXY_URLS.

If you have the libxml2 and libxslt Python packages installed, the proxy can also apply some data transformations, which are given in XDPROXY_TRANSFORMATIONS. Each transformation specifies the source mimetype (a regular expression that has to match the mimetype currently downloaded), the XSLT transformation to apply to it and the resulting target mimetype. Example:
XDPROXY_TRANSFORMATIONS = {
  'somedata': (
     r'(?i)^text/xml;\s*?charset=UTF-8$',
     '/opt/bscw/xslt/somedata.xsl',
     'application/json; charset=UTF-8')
}

XDPROXY_ENABLED = False
XDPROXY_TRANSFORMATIONS = {}
XDPROXY_URLS = []

BSCW_LOGGING

BSCW offers detailed logging information on various components of the system. The purpose of logging is mainly for debugging and problem identification. It should be noted that system logs may contain personal detail and sensitive information.

Logging is enabled by default to log error conditions:
BSCW_LOGGING = {
    'sys': ('ERROR', 'sys.log'),
}
This creates the log file sys.log where records from all loggers with the log level ERROR will be logged. To create log files for specific loggers with more detailed log levels add the following entries, for example:
BSCW_LOGGING = {
    'sys': ('INFO', 'sys.log'),
    'ldap': ('DEBUG', 'ldap.log'),
    'mda': ('DEBUG', 'mda.log')
}
Where 'ldap' specifies the logger for the BSCW ldap package, and 'mda' the logger for the BSCW Mail Delivery Agent.

# BSCW_LOGGING = {
#    'sys': ('WARN', 'sys.log'),
#    'arc': ('ERROR', 'arc.log'),
# }

BSCW_DEBUG

BSCW provides the possibility to debug database objects live. To make this operation available to administrators, BSCW_DEBUG must be set to one of the following values:
0 - disabled
1 - read access to the database for administrators
2 - read/write access to the database for administrators

BSCW_DEBUG = 1

WAIT_ARCHIVING

ARCHIVE_LIMIT

BSCW allows archiving of large workspaces by starting a background process for the archive task (and likewise for extraction of archives). For smaller archives the task is coupled with the CGI process so that the user will see immediate feedback.

WAIT_ARCHIVING defines the time in seconds that a CGI process will wait for the archive or extract task to complete before it returns with an adhoc response to the user. The time must be less than the http server’s timeout (typically 300 sec.).

ARCHIVE_LIMIT defines the maximum size of downloadable archives. You may use this to prevent denial-of-service attacks caused by users creating archive-bombs. By default ARCHIVE_LIMIT is set to 2G. Possible values for the sizes are strings which may be specified in bytes or kilo- (mega-, giga-, tera-) bytes with an additional k (K), M, G or T suffix. E.g. valid values for ten mega-bytes are 10485760 or '10M'.

DOWNLOADBUTTON_CONFIRM defines the size limit from where quick downloads will be started only after some confirm request. The download button is placed inside the toolbar. By default everything smaller 100M will be downloaded directly. Possible values for the sizes are strings which may be specified in bytes or kilo- (mega-, giga-, tera-) bytes with an additional k (K), M, G or T suffix. E.g. valid values for ten mega-bytes are 10485760 or '10M'.

WAIT_ARCHIVING = 10
ARCHIVE_LIMIT = '2G'
DOWNLOADBUTTON_CONFIRM = '100M'

packages_state

Please do not change packages_state. It controls automatic enabling/disabling of new/obsolete PACKAGES in bsadmin update_defaults.

packages_state = 6

4.3. conf/config_actions.py¶

The config_action.py configuration file allows to redefine roles.

4.4. conf/config_cal.py¶

This is the configuration file for the calendar. Please note that not all entries are meant to be configured by the administrator here. Especially the settings of flags, categories and appoint_status should not be changed.

BSCW administrators may change the default preferences for each user’s calendar here – the calendar_flags contains the sum of all enabled calendar flags (cf. list of flags). The file also contains defaults for the display of appointments in different views. For each view (y = year, m = month, w = week, d = day) a list of potential ('allowed_x') and displayed ('view_x') style items is specified.

4.5. conf/config_clientmap.py¶

The config_clientmap.py configuration file defines the mapping between web browsers and their supported options.

4.6. conf/config_controls.py¶

The config_controls.py configuration file defines access right independent parameters for BSCW operations. Generally it is not advised to make changes without consulting our support staff.

4.7. conf/config_convert.py¶

The conversion tool configuration is automatically performed by the bsadmin update_defaults script. This script will search the local system for archiver, encoder or converter commands and generate a <bscw-runtime-path>/conf/config_convert.py converter configuration file. To locate a converter command the script uses some internal heuristics and evaluates the users’ environment search path variable (PATH (Unix) resp. Path (Windows)).

In the following paragraph the syntax of the converter configuration file is explained. The system commands for archiver, encoder or converter tools are given in the following three lists respectively:

The Encoders list contains triples (type, encoder, decoder) with

type            the encoding-type for the encoding tool
encoder         the shell command to encode a file
decoder         the shell command to decode a files

Example:
    Encoders = [
        ('compress',
            '/usr/bin/compress -f -c %(src)s > %(dest)s',
            '/usr/bin/uncompress -c < %(src)s > %(dest)s',
        ),
        ('gzip',
            '/usr/bin/gzip < %(src)s > %(dest)s',
            '/usr/bin/gzip -d < %(src)s > %(dest)s',
        ),
        ('x-bzip2',
            '/usr/bin/bzip2 < %(src)s > %(dest)s',
            '/usr/bin/bzip2 -d <
            %(src)s > %(dest)s',
        ),
        ('x-uuencode',
            '/usr/bin/uuencode %(src)s dummy > %(dest)s',
            '/usr/bin/uudecode -p %(src)s > %(dest)s',
        ),
    ]

The Converters list contains 5-tuples (src_type, dest_type, quality_factor, command, info) with

src_type        the mime-type from the source file
dest_type       the mime-type from the destination file
quality_factor  a number between 0 and 1 to estimate the quality
                of the conversion. If you have more than one
                tool for the same conversion, the one with the
                best quality is chosen.
command         the shell command to convert a file
info            information about what is lost during the conversion

Example::

    Converters = [
        ('application/pdf', 'text/plain', '0.5',
            '/usr/bin/pdftotext -enc UTF-8 %(src)s %(dest)s',
            'layout/images',
        ),
        ('application/postscript', 'text/plain', '0.5',
            '/usr/bin/ps2ascii -sOutputFile=%(dest)s -q -dBATCH %(src)s',
            'layout/images',
        ),
        #...
    ]

The Programs list contains 5-tuples (name, path) with

name            the external converter program name
path            the system path to the external program name

The shell commands have to be specified with an absolute pathname and are normally executed in a temporary directory in BSCW Temp. In a shell command the following patterns can be used:

%(py)s              absolute path of the python executable
%(cnv)s             absolute path of the BSCW converters directory
%(src)s             the absolute path of the source file
%(dest)s            the base name of destination file
%(pid)s             process id of the converter process

For the Converters list additionally the following pattern can be used:

%(charset)s         character set encoding for documents with a
                    "text/*" content-type.

In squared bracket some additional parameters can be set:

[S_EXT=.xxx]            specifies the extension of the source file
[D_EXT=.xxx]            specifies the extension of the destination file
[D_NAME=%(dest)s.xxx]   or
[D_NAME=%(src)s.xxx]    specifies the name of the destination file
[E_DIR=xxx]             specifies a directory, where the tool should be executed

Multiple parameters can be separated in the squared bracket with a semicolon.

To avoid automatic manipulation of the following lists by bsadmin update_defaults enable the following line below (use at own risk, future updates may fail):

__keep__ = ['Encoders', 'Converters']

To regenerate the converter file, e.g. after you installed new converters or adapted your environment search path, run the script with the options -s (to skip a Python import check) and -v (to print some information about found converter commands):

$ bin/bsadmin update_defaults -h
Usage:
 bsadmin update_defaults [-s|-e] [-i] [-v|-vv|...] [-w|-ww|...]
 bsadmin update_defaults -h

    Update conf/__init__.py and conf/config.py

optional arguments:
 -s             skip import check
 -e             exit on package error
 -i             reinitialize conf/__init__.py
 -v -vv ...     verbosity
 -w -ww ...     warning level
 -h             show this help message and exit

$ bin/bsadmin update_defaults -s -v
...
Found "Programs" (located):
 '7z': '/usr/bin/7za'
 'bzip2': '/usr/bin/bzip2'
 'cjpeg': None
 'compress': '/usr/bin/compress'
 'convert': '/usr/bin/convert'
 'djpeg': None
 'gif2tiff': None
 'gm': '/usr/bin/gm'
 'gzip': '/usr/bin/gzip'
 'html2text': '/usr/bin/html2markdown'
 'java': '/usr/bin/java'
 'lynx': '/usr/bin/lynx'
 'markdown': '/usr/bin/markdown_py'
 'pdftotext': '/usr/bin/pdftotext'
 'perl': '/usr/bin/perl'
 'pildriver': None
 'ps2ascii': '/usr/bin/ps2ascii'
 'tar': '/usr/bin/tar'
 'tesseract': '/usr/bin/tesseract'
 'uncompress': '/usr/bin/uncompress'
 'unoconv': '%(py)s %(cnv)s/unoconv/unoconv --pipe=%(pid)s'
 'unzip': '/usr/bin/unzip'
 'uudecode': '/usr/bin/uudecode'
 'uuencode': '/usr/bin/uuencode'
 'w3m': '/usr/bin/w3m'
 'weasyprint': '/usr/bin/weasyprint'
 'wkhtmltopdf': None
 'zip': '/usr/bin/zip'
conf/config_convert.py : updated...

4.8. conf/config_countries.py¶

The config_countries.py file defines country codes (based in ISO 3166 standard) for selections lists.

4.9. conf/config_grid.py¶

The config_grid.py file defines the appearance and column layout of the Web interface grid.

4.10. conf/config_guided_tours.py¶

The config_guided_tours.py configures the available user guided tours.

4.11. conf/config_help.py¶

The config_help.py file defines mappings from the BSCW context sensitive help to online help HTML pages.

4.12. conf/config_html_ui.py¶

It is possible to configure the folder views for every folder type by altering the corresponding entries in config_html_ui.py. Additionally single columns can be hidden in specific users levels. To achieve this the following entries of the folder type list must be changed:

V_ANY = -1
V_ADM = V_ALL | V_DEF | V_MIN
V_AD  = V_ALL | V_DEF
V_A   = V_ALL

UI_VIEWS = {
    'Folder': {
        #...
        'columns': [
            # (colbit, position, presets, ui_profiles)
            (col_icon, 100, V_ANY, ui_yes, ),
            (col_name, 200, V_ANY, ui_yes, ),
            # ...
        ]
    }
}

4.13. conf/config_icon.py¶

The config_icon.py file allows to define mappings of names to a icon resources - i.e. a CSS class names.

4.14. conf/config_icons.py¶

The config_icons.py file maps BSCW objects to image files.

4.15. conf/config_meet.py¶

This is the configuration file for synchronous collaboration tools, i.e. social networks.

4.16. conf/config_menus.py¶

The config_menu.py file specifies the BSCW 7 menu configuration.

4.17. conf/config_metadata.py¶

The config_metadata.py file specifies the meta data for BSCW objects.

4.18. conf/config_mimegroups.py¶

The config_mimegroups.py file maps MIME-types of different applications in groups, eg. Microsoft Office.

4.19. conf/config_mime_icons.py¶

The config_mime_icons.py file configures for the MIME-types icons in BSCW 7.

4.20. conf/config_mimemsg.py¶

While the translations in different languages of all built-in MIME-type messages are stored in lg_msgconfig.py, the file config_mimemsg.py keeps all user-defined MIME-type messages defined by an BSCW administrator.

4.21. conf/config_mime.py¶

This is the configuration file for the MIME-types. Default MIME-type information for BSCW details can be extended or modified directly for system-wide effect. To add MIME-types, add an entry to the list below. Also consider adding an entry to bs_iconconfig.py if the type should have its own icon (otherwise the Unknown icon will be used) and adding an entry to config_mimemsg.py for the description of the MIME-type. The format for entries is:

name = (MIME-Type, suffix0, suffix1, ...)

where

name is the name of type’s icon (in config_icon.py) and description (in config_mimemsg.py). The name must be unique and conform to Python naming conventions;
MIME-Type consists of a type and a subtype divided by a slash (use lower case letters);
suffix0 ... suffixn are used by document conversion assistant and to determine the document type by extracting a file archive (<= 3 characters recommended).

Note

Only a subset of the IANA (and common, non-standard) media-types are specified here.

4.22. conf/config_mpick.py¶

The config_mpick.py file allows to overload non-existing BSCW database object classes with replacement classes at runtime. BSCW uses this mechanism to replace database objects for BSCW extension package classes which have been disabled.

4.23. conf/config_portlets.py¶

The config_portlets.py file provides configuration custom portlets.

4.24. conf/config_prio_categ.py¶

The config_prio_categ.py file configures settings for priorities and categories.

4.25. conf/config_quicksearch.py¶

The config_quicksearch.py file provides configuration for the BSCW quick search.

4.26. conf/config_search.py¶

The config_search.py file allows to configure the BSCW main search keys. Configured search keys are indicated with MainSearchKey() entries in this file. All defined main search keys are immediately available in the “+” menu of a search operation, e.g.

MainSearchKey('org:theme')
MainSearchKey('org:region')
MainSearchKey('org:location')
MainSearchKey('org:status')

4.27. conf/config_service.py¶

The config_service.py file provides configuration the Windows service.

4.28. conf/config_styles.py¶

The config_styles.py file provides configuration for style sheet handling.

4.29. msg/<lang>/lg_msgconfig.py¶

The lg_msgconfig.py file specifies numerous text strings which are used in the interface of the BSCW server. Since these text strings are obviously language dependent, they are stored in the respective language directories, i.e., there exists a file lg_msgconfig.py in msg/en as well as in msg/de and possibly in other language directories.

While the default language files are located in the distribution library directory <bscw-path>/lib/bscw-7.6.1-<rev>-py3*/bscw/msg/* changes should be located in the corresponding BSCW instance runtime directory <bscw-runtime-path>/bsext/msg/*.

For example to change translations from msg/en/lg_msgconfig.py for your instance create a <bscw-runtime-path>/bsext/msg/en directory and copy the distribution <bscw-path>/lib/bscw-7.6.1-<rev>-py3*/bscw/msg/en/lg_msgconfig.py file to this location. Now you can edit <bscw-runtime-path>/bsext/msg/en/lg_msgconfig.py and adapt it for your BCSW instance.

The file consists of a set of entries where each entry has the form:

InternalName = 'Interface text string'

where InternalName is the name of an entity in the BSCW server source code and Interface text string is the external representation of the entity in the user interface. Obviously, InternalName is the same character string for all languages whereas Interface text string is, in general, specific for each language. For example, the lg_msgconfig.py file for English contains the following two lines

Folder = 'Folder'
ChangeEvent = 'changed'

whereas the lg_msgconfig.py file for German contains

Folder = 'Ordner'
ChangeEvent = 'geändert'

Note the internal name and its external representation may be the same as for “Folder” (usually only in English) or it may be different as for “ChangeEvent” and “changed” (and, in general, for other languages than English).

A BSCW system administrator may modify the user interface of his or her BSCW server by replacing interface text strings, e.g., if the ChangeEvent entry is modified to

ChangeEvent = 'modified'

the change event would appear with the name “modified” in the user interface.

Whereas InternalName must always be one word conforming to Python naming conventions, Interface text string may consists of several words and may include HTML mark-up and also parameters for variable parts and must therefore be enclosed in quotes (single ', double " or triple """). For example:

ChAccessEvent     =     'access rights changed'
no_objects        =     '<P><STRONG>No objects, currently.</STRONG></P>'
CreateEventMsg    =     'created by %(name)s, %(date)s'

The entries are not listed in detail here.

The lg_msgconfig.py file for English is the “default” language file, i.e., if a lg_msgconfig.py file for a language different from English is lacking a translation, the entry is taken from the English file. In order to facilitate comparison of the lg_msgconfig.py files for different languages, the order of the entries in the files should not be modified, nor should entries be removed completely. Entries which should not or cannot be translated, should be commented out for performance reasons. Commenting out entries from a lg_msgconfig.py file for languages other than English may be sensible, e.g., if a translation is not desired which is normally the case for system messages.