3. Installation procedure for Unix

These are the installation instructions for BSCW 5 on Unix machines. If you are upgrading an existing BSCW server instance please go through section 2.4 Upgrading to BSCW 5.2.6.

3.1. System requirements

For approximately 200 users the BSCW server requires the following server hardware:

  • Intel Core/Xeon or AMD EPYC/Ryzen (>3,2 GHz) 64-bit server system with at least 6 cores (or comparable systems of other manufacturers).
  • 8 GB RAM
  • at least 500 GB hard disk space (the BSCW installation requires approx. 200 MB disk space)

Additionally the following software is required:

  • Apache HTTP Server 2.4
  • Python 2.7 interpreter
  • extensions for Python (optional)
    • pylucene - required for full text indexing support (package PyLucIndex)
    • python-ldap - required for LDAP/Active Directory bindings (package ldap)
  • (optional) converter software for the BSCW preview feature

Before installing BSCW, first install the Apache HTTP server, the Python interpreter, the desired Python extension packages or converter software:

  • OrbiTeam supports supports Debian based distributions (e.g Debian, Mint, Ubuntu) and Enterprise Linux/Fedors based distributions (e.g. Fedora, RHEL, CentOS).
  • Generally it is recommended to choose a Unix distribution which has native support for the required software as the desired optional Python extensions or converter software. For example the LibreOffice suite should be available as installable package.

Note

  • On EL based systems you need to add the EPEL repository, see https://fedoraproject.org/wiki/EPEL for details.

    • CentOS Stream 8:

      $ su -
# dnf config-manager --set-enabled powertools
# dnf install epel-release epel-next-release

    • RHEL 8:

      $ su -
# subscription-manager repos --enable codeready-builder-for-rhel-8-$(arch)-rpms
# dnf install https://dl.fedoraproject.org/pub/epel/epel-release-latest-8.noarch.rpm

  • On systems which do not allow execution of set-group-id scripts, e.g. Linux, a C compiler (gcc) with installed system (kernel) C headers is required to compile a binary wrapper.

In order to send registration and report emails, BSCW finally needs access (via SMTP) to a mail server (Unix or Windows based).

3.2. Installation

Before installing BSCW ensure the Web server, the Python interpreter, the desired Python extension packages and the converter software are installed.

On Linux systems it is recommended to use a Debian or a Enterprise Linux/Fedora based distribution. Generally the Python packages of the distribution should be preferred.

Packages name(s) for these Linux distributions:

  • Debian based systems: apache2 python2.7 python-ldap
  • EL based systems: httpd mod_ssl python2 python-ldap

Additionally install the converter software required for BSCW preview, see Software for BSCW Preview for details.

The BSCW server software distribution is available as tar archive bscw-5.2.6-<rev>-py27.tar.gz

The name of the download file contains BSCW and Python version numbers – e.g. bscw-5.2.6-<rev>-py27.tar.gz contains BSCW version 5.2.6 for Python 2.7. Please make sure to install the latest version of BSCW and always provide your version number when contacting support staff.

There may be additional patch releases available after the latest release – check the BSCW product home page https://www.bscw.de for latest updates that have been released for download.

The BSCW directory should not be accessible via the DocumentRoot or any other alias directives of your HTTP server. The path to the BSCW directory needs only “search permission” for the user/group ID that the HTTP server uses.

The BSCW server CGI scripts are executed (set-group-id) with the group ID bscw, which is the primary group ID of the BSCW system user. Hence access rights for the group ID bscw will be inherited during execution of all BSCW CGI scripts. To ensure an error free operation of the BSCW server:

  • the set-group-id bit of the BSCW CGI scripts has to be set (which is done automatically done by the BSCW setup procedure)
  • the BSCW directory <bscw-path> (and all files and directories below) should belong the group ID bscw
  • the file system of the BSCW directory <bscw-path> must not be mounted with the nosuid option

If the set-group-id execution of the BSCW CGI script fails you will get an Error: Wrong group id while BSCW operation. To fix this problem see the note of section 3.4.3 Administrator account.

Note

  • When installing on a Linux-based OS you must make sure a working compiler (GCC/CC) is installed (due to limitations of set-group-id execution for scripts on Linux, the compilation of the CGI binary wrapper became mandatory).
  • (Optional) if the binary python package setproctitle is installed BSCW processes are displayed with more telling names (Linux):
    • Debian based systems: python-setproctitle
    • EL based systems: python2-setproctitle

Ensure to disable the SELinux extension (which is enabled by default on Enterprise Linux (EL) based systems), e.g. usually set in /etc/selinux/config:

#SELINUX=enforcing
SELINUX=permissive

and reboot your system.

Generally the following file layout is proposed for BSCW instances

/opt/bscw/                                  # BSCW user home directory
                                            # (as defined in /etc/passwd!)

/opt/bscw/.bscw/                            # BSCW instance(s) information
/opt/bscw/.bscw/bscw.conf
/opt/bscw/.bscw/bscw_conf.py

/opt/bscw/lib/                              # BSCW distribution libraries
/opt/bscw/lib/bscw-5.2.6-<rev>-py27/        # BSCW distribution 5.2.6
/opt/bscw/lib/bscw-5.2.6-<rev>-py27/bin
/opt/bscw/lib/bscw-5.2.6-<rev>-py27/bscw    # BSCW executable code
/opt/bscw/lib/bscw-5.2.6-<rev>-py27/doc     # BSCW documentation
/opt/bscw/lib/bscw-5.2.6-<rev>-py27/etc
/opt/bscw/lib/bscw-5.2.6-<rev>-py27/lib     # BSCW third party modules

/opt/bscw/srv/                              # BSCW instances
/opt/bscw/srv/<hostname>/                   # BSCW instance runtime
/opt/bscw/srv/<hostname>/bin/               # BSCW instance executables
/opt/bscw/srv/<hostname>/bin/bsadmin
/opt/bscw/srv/<hostname>/conf/              # BSCW instance configuration
/opt/bscw/srv/<hostname>/conf/config.py
/opt/bscw/srv/<hostname>/etc/               # BSCW configuration hints
/opt/bscw/srv/<hostname>/libexec/           # BSCW instance programs
/opt/bscw/srv/<hostname>/var/
/opt/bscw/srv/<hostname>/var/cache/         # BSCW instance template cache
/opt/bscw/srv/<hostname>/var/data/          # BSCW instance data
/opt/bscw/srv/<hostname>/var/log/           # BSCW instance log files
/opt/bscw/srv/<hostname>/var/run/           # BSCW instance state
/opt/bscw/srv/<hostname>/var/www/           # BSCW instance web resources

The BSCW layout allows to install multiple BSCW instances in the runtime directory /opt/bscw/srv, which all share the same BSCW program code located in the library directory /opt/bscw/lib.

As a prerequisite a suitable Python interpreter version and the Apache HTTP server must be available on the system before installing BSCW. For best performance, the BSCW libraries and instances should be located on a file system local to the host where your HTTP server runs.

The installation program of the BSCW software must be run as superuser (root). The installation procedure will look for the BSCW system user bscw and uses the home directory of this user as installation base directory for BSCW (which might alter from /opt/bscw. If no BSCW user is found a new BSCW system user bscw with an own group bscw and a home directory /opt/bscw is proposed and then created.

Note

  • /opt/bscw is the proposed location for the BSCW users home directory (resp. the BSCW installation base directory). Generally the installation procedure uses the BSCW users’ home directory (as defined in /etc/passwd) as default installation base directory.
  • If you want to install BSCW in another location different from the home directory of the BSCW user you may want to specify an alternate base directory. The base directory of a BSCW installation defines the directory where the installation program will create the ./lib directory containing the BSCW distribution and the ./srv directory to create BSCW runtime instances. Usually the base directory is equal to the BSCW users’ home directory and does not need to be changed.
  • During the installation procedure you may specify an alternate BSCW system user name or home directory.

After creating or locating the BSCW system user the installation procedure will extract the BSCW distribution archive in the library directory (usually /opt/bscw/lib) and the BSCW setup procedure is called and run as BSCW system user bscw.

The BSCW setup procedure will allow to update existing BSCW instances or to create new BSCW instances. All required BSCW instance parameters are identified via command line dialogs.

Finally the installation procedure tries to identify the user of the Apache HTTP server and changes the ownership of the upload directory for raw files to the Apache user.

To start the installation, extract the BSCW distribution archive and run the install.sh script as superuser

$ su -
# id
uid=0(root) gid=0(root) groups=0(root)
# tar xf bscw-5.2.6-<rev>-py27.tar.gz
# cd bscw-5.2.6-<rev>-py27
# ./install.sh

It is highly advisable to use only the distribution install script ./install.sh as superuser. The script automatically determines required owner/permission changes and performs configuration checks (systemd) which are not possible as BSCW system user “bscw”.

Note

If you do not want to run the install.sh script as superuser you may install BSCW completely manual as follows (necessary permisson changes may not be performed then!):

  • login as bscw user

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

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

    $ cd $HOME
$ mkdir lib

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

    $ cd /tmp
$ tar xf bscw-5.2.6-<rev>-py27.tar.gz
$ cd $HOME/lib
$ tar xf /tmp/bscw-5.2.6-<rev>-py27/bscw-5.2.6-<rev>-py27.tar

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

    $ cd $HOME/lib/bscw-5.2.6-<rev>-py27
$ python ./bin/setup.py <bscw-runtime-path>

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

# ./install.sh

Enter BSCW system user name: [bscw]

Enter BSCW user home directory: [/opt/bscw]

Enter BSCW base directory: [/opt/bscw]

Extracting BSCW 5.2.6 distribution in /opt/bscw/lib

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

Please enter the BSCW server root
(use a fully qualified domain name - an IP address is not allowed).
The server root specifies the visible URL for this instance, e.g.
http://host.domain.org or https://host.domain.org
(may be left empty):

BSCW server root: https://bscw.domain.org

Please enter the name of your BSCW instance directory
(if left empty in directory
/opt/bscw/srv
the default [bscw.domain.org] is created):

BSCW instance name: [bscw.domain.org]
target '/opt/bscw/srv/bscw.domain.org' does not exist - creating...

Please enter the host name (FQDN) or the IP address
of your mail host (MTA) to relay BSCW emails
(may be left empty):

 Mail host name or IP address: mail.domain.org

Please enter email address and login name of the BSCW administrator:

 Email address: admin@domain.org
 BSCW login name: admin
 Enter Password:
 Re-type password:

Please enter the BSCW server Realm - used in Authentication dialog
and shown on the welcome page of the server.
(may be left empty and defaults to 'BSCW Shared Workspace Server')
Note: If you are running different BSCW servers on one host
      then you must use a different realm for each server.

 Realm:

Please enter the BSCW public URI prefix as used for public access URL, e.g.
http://my.bscw.de/pub/bscw.cgi
(may be left empty and defaults to 'pub')
Note: If you are running different BSCW servers on one host without using
virtual hosts then you must use a different URI prefix for each server.

 BSCW public prefix:

Please enter the BSCW secure URI prefix as used for secure access URL, e.g.
http://my.bscw.de/sec/bscw.cgi (requires authentication)
(may be left empty and defaults to 'sec')
Note: If you are running different BSCW servers on one host without using
virtual hosts then you must use a different URI prefix for each server.

 BSCW secure prefix:

Initial configuration:
SERVER_ROOT = "http://bscw.domain.org"
SMTP_HOST = "mail.domain.org"
SERVER_ADMIN = "admin@domain.org"
SERVER_ADMINS = [ "admin" ]

Are these settings correct (yes/no)? yes

conf/config.py updated
'/opt/bscw/srv/bscw.domain.org/conf/__init__.py' updated
no config_run.pyc yet
Import core modules ...
Link destination '/opt/bscw/lib/bscw-5.2.6-<rev>-py27/extensions' does not exist
config_convert.py created
bsadmin update_defaults
bsadmin manage_servers -u
2020-08-28 09:28:46 bsadmin chkconfig -check-access
2020-08-28 09:28:46 access checks...
cc -o var/run/run_bscw var/run/run_bscw.c
2020-08-28 09:28:46 Actual license: OK (none)
2020-08-28 09:28:46 bsadmin start
2020-08-28 09:28:47 bsadmin garbage -license
2020-08-28 09:28:47 GC actual license: OK (none).
                      is invalid for BSCW 5.2
                    Try installing Evaluation licence
                    Your server: org.domain.bscw:443S.sec
                    Evaluation licence expires:   20201127
                    Evaluation licence max users: 200
[...]
bsadmin convert -check-access
Configure 'gzip' compression ...
Configure 'static' resources '/opt/bscw/lib/bscw-5.2.6-<rev>-py27/bscw/resources'...
 (Long time future expire dates)
Configure secure prefix '/sec/' (Apache 2) ...
 (HTTP_AUTHORISATION passed to BSCW)
 (Cookie authentication enabled)
Configure public prefix '/pub/' (Apache 2)...
 (No authentication)
Configure secure prefix '/sec/' (Apache 24) ...
 (HTTP_AUTHORISATION passed to BSCW)
 (Cookie authentication enabled)
Configure public prefix '/pub/' (Apache 24)...
 (No authentication)

Creating Apache HTTP server configuration files in
/opt/bscw/srv/bscw.domain.org/conf/apache{2,24}
   mod.conf ... module configuration file
  site.conf ... virtual host site configuration file
  bscw.conf ... BSCW configuration file
bsadmin conf_apache
bsadmin index_page
register admin user
user admin registered, address:
    admin@domain.org: (is_owned_by_user)

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

BSCW instance created: '/opt/bscw/srv/bscw.domain.org'
Make sure to include the BSCW Apache HTTP server configuration
(see above) in your local Apache HTTP configuration
you may need to restart your web-server

Installation succeeded. For next steps please check
/opt/bscw/lib/bscw-5.2.6-<rev>-py27/README.txt

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

Note

If the BSCW server does not start up properly, see the file /tmp/bscw-setup.log or <bscw-runtime-path>/var/log/bscw.log in the instance runtime directory for details and error messages. The frequently asked questions (FAQ) list (https://www.bscw.de/en/support/) might also be helpful.

3.3. Software for BSCW Preview

The BSCW preview component displays thumbnail images for uploaded documents. If the user moves the mouse pointer over an BSCW object icon in the type column, an image of the first page of an document is shown.

To enable the BSCW preview component the following additional software must be available on the hosting system:

  1. Java Runtime Environment
  2. HTML/PDF converters: WeasyPrint (preferred) or PhantomJS
  3. Ghostscript
  4. GraphicsMagick
  5. LibreOffice
  6. Text/HTML converters: markdown2, html2text
  7. Image converter: PIL
  8. Metadata extraction: Tika-Server (optional)

In particular install this software components as follows:

  1. Java Runtime Environment 8 or 11

    Java platform independent programming language

    • The Java runtime environment (JRE) of the distribution should be installed.

      Packages name(s) for common Linux distributions:

      • Debian based systems: openjdk-8-jdk resp. openjdk-11-jdk
      • EL based systems: java-1.8.0-openjdk resp. java-11-openjdk

  2. HTML/PDF converters

    Install one of the following HTML/PDF converters. WeasyPrint gives better results and is therefore preferred, while PhantomJS is easier to install.

2.1 WeasyPrint (https://weasyprint.readthedocs.io)

WeasyPrint requires Python 3 (see https://weasyprint.readthedocs.io/en/latest/install.html#linux for details)

  • Debian based systems

    $ su -
# apt install python3-pip python3-setuptools python3-wheel
# apt install \
   build-essential \
   python3-dev python3-cffi \
   libcairo2 libpango-1.0-0 libpangocairo-1.0-0 libgdk-pixbuf2.0-0 \
   libffi-dev shared-mime-info
# pip3 install WeasyPrint

  • EL based systems

    $ su -
# dnf install python3-pip python3-setuptools python3-wheel
# dnf install \
   redhat-rpm-config \
   python3-devel python36-cffi libffi-devel cairo pango gdk-pixbuf2
# pip3 install 'WeasyPrint<53.0'

Note

WeasyPrint >= 53.0 requires pango > 1.44

2.2 PhantomJS 2.1 (http://phantomjs.org/)

PhantomJS is a headless WebKit scriptable with a JavaScript API. It is available as distribution package:

  • Debian based systems: phantomjs

Alternatively it can be can be downloaded from:

http://phantomjs.org/download.html

  • For other Linux systems binaries are available at:

    https://bitbucket.org/ariya/phantomjs/downloads/phantomjs-2.1.1-linux-i686.tar.bz2
https://bitbucket.org/ariya/phantomjs/downloads/phantomjs-2.1.1-linux-x86_64.tar.bz2

  • Copy the binary bin/phantomjs in a location accessible by your PATH, e.g. in /usr/local/bin/phantomjs

  1. Ghostscript 9 (https://ghostscript.com)

    Ghostscript is an interpreter for the PostScript language and for PDF

    • The Ghostscript interpreter version of the distribution should be installed. Additionally the standard Ghostscript fonts are required.

      Packages name(s) for common Linux distributions:

      • Debian based systems: ghostscript gsfonts
      • EL based systems: ghostscript ghostscript-tools-fonts

  2. GraphicsMagick (http://www.graphicsmagick.org)

    GraphicsMagick is a library for image processing

    • The GraphicsMagick version of the distribution should be installed.

      Packages name(s) for common Linux distributions:

      • Debian based systems: graphicsmagick
      • EL based systems: GraphicsMagick

      After installation check if GraphicsMagick correctly finds Ghostscript:

      $ gm convert -list Delegates
...
   ps<=>pdf   "gs" -q -dBATCH -dSAFER -dMaxBitmap=50000000 -dNOPAUSE
              -sDEVICE=pdfwrite "-sOutputFile=%o" -- "%i" -c quit

  • The user avatar generation requires the DejaVu Sans fonts:

    Packages name(s) for common Linux distributions:

    • Debian based systems: fonts-dejavu
    • EL based systems: dejavu-sans-fonts

  1. LibreOffice (https://www.libreoffice.org/)

    LibreOffice is a open source office suite. At least LibreOffice version 7 is required, best use the current release of LibreOffice.

    • The LibreOffice version of the distribution should be installed.

      Packages name(s) for common Linux distributions:

      • Debian based systems: libreoffice python3-uno
      • EL based systems: libreoffice-calc libreoffice-draw libreoffice-emailmerge libreoffice-graphicfilter libreoffice-impress libreoffice-math libreoffice-writer libreoffice-pyuno

    • For better conversion results install the Microsoft TrueType core fonts

      • Debian based systems: ttf-mscorefonts-installer

      • EL based systems:

        $ su -
# dnf install cabextract curl fontconfig xorg-x11-server-utils
# rpm -i --nodeps https://deac-ams.dl.sourceforge.net/project/mscorefonts2/rpms/msttcore-fonts-installer-2.6-1.noarch.rpm

    • Ensure the home directory of the Apache HTTP server user is writable for the Apache HTTP server user, because LibreOffice creates temporary files in the users’ home directory.

      • Debian based systems:

        $ su -
# chown www-data. /var/www

      • EL based systems:

        $ su -
# chown apache. /usr/share/httpd

    Attention

    Be sure the Python UNO bridge is installed!

  2. Text/HTML converter

    Install the markdown2 and html2text converters as follows:

    • markdown2 converts text to HTML using the markdown markup.

      Since no distribution packet exists, use pip package manager to download and install markdown2:

      $ su -
# pip install markdown2

    • html2text converts HTML to text using the markdown markup

      Packages name(s) for common Linux distributions:

      • Debian based systems: python-html2text
      • EL based systems: python-html2text

      Note

      On Debian python-html2text is installed as html2markdown.

      If your distribution does not support a native version, use pip to download and install html2text:

      $ su -
# pip install html2text

  3. Image converter

    For image conversion the Python Imaging Library is required

    Packages name(s) for common Linux distributions:

    • Debian based systems: python-pil

    • EL based systems:

      $ su -
# pip install pillow

  1. Apache Tika

    BSCW utilizes the Apache Tika toolkit (https://tika.apache.org) to extract metadata and text from uploaded documents. To enable the Apache Tika a Java Runtime Environment 8 or 11 must be available on the server host.

    To accelerate metadata extraction it is possible to install an optional standalone tika-server. For installation download the tika-server JAR archive from

    https://www.apache.org/dyn/closer.lua/tika/2.2.?/tika-server-standard-2.2.?.jar

    and copy it into the BSCW distribution

    $ cd $HOME/lib/bscw-5.2.6-<rev>-py27
$ cp tika-server-2.2.?.jar bscw/libexec/tika
$ chmod 644 bscw/libexec/tika/tika-server-2.2.?.jar

    Additionally the tika Python package is required, use pip to download and install tika

    $ su -
# pip install tika

If the prerequisites 1-7 are met run

  • bsadmin update_defaults to generate a new BSCW converter configuration (<bscw-runtime-path>/conf/config_convert.py). Use the verbose option (-v) to check if BSCW found the required converter programs to create the previews files:

    $ cd <bscw-runtime-path>
$ ./bin/bsadmin update_defaults -v
...
Converter auto-configuration:
 Found Commands:
  'gm': '/usr/bin/gm'
  'java': '/usr/bin/java'
  'phantomjs': '/usr/local/bin/phantomjs'
  'unoconv': '%(py)s %(cnv)s/unoconv/unoconv --pipe=%(pid)s'
  ...
config_convert.py updated

Optionally you may create for all existing documents the required preview files using the bsadmin preview command:

$ ./bin/bsadmin preview
Usage:
 bsadmin preview list
 bsadmin preview create [-v|-q] [-f|-ff]  [<oid0> ... <oidn>]
 bsadmin preview delete [-v|-q]           [<oid0> ... <oidn>]
 bsadmin preview [-h]

    Generate Document preview documents

 positional arguments:
    list      print preview states and preview document file names
    create    created preview for documents in 'var/cache/preview'
    delete    deletes preview states and generated preview documents

 optional arguments:
    -f        force upgrade of all previews
    -ff       force upgrade of previews with state 'FAILURE'
    -v        verbose
    -q        quiet
    -h        show this help message and exit

Note

  • On large BSCW installations bsadmin preview create may take a very long period (weeks!)
  • The execution of bsadmin preview create is not mandatory, because preview files are automatically scheduled for background creation the first time an existing folder is read by an user.

In the case of problems with automatic preview file generation enable logging by adding the following entry to BSCW_LOGGING in <bscw-runtime-path>/conf/config.py. The BSCW preview component will then log into <bscw-runtime-path>/var/log/prev.log:

BSCW_LOGGING = {
    'sys': ('WARN', 'sys.log'),
    'prev': ('DEBUG', 'prev.log'),
    # ...
}

An preview log file entry:

2020-02-10 11:35:07 prev DEBUG pid 123 error: libexec/conv: Document#456
    ...gm convert: Unable to get type metrics...

indicates the ghostscript standard fonts are missing resp. are not properly installed or no DejaVu Sans fonts are installed on the system.

Note

To disable the BSCW preview feature add an entry CREATE_PREVIEWS in <bscw-runtime-path>/conf/config.py:

CREATE_PREVIEWS = False

3.4. Configuration

The configuration includes the configuration of your Web server and the configuration of the BSCW server.

3.4.1. Apache HTTP Server Configuration

BSCW requires in addition to a (virtual) web service for user access, a second (virtual) web server running on localhost (127.0.0.1). This second (virtual) web server enables BSCW services (e.g. the User Notification Services (UNO) of section 7.4.1 or the alarm service) to access the BSCW database server via HTTP using the following URL:

http://localhost/pub/bscw.cgi/

Note

The port, the script alias path and the script name may be changed by altering the configuration directives HTTP_LOCAL_PORT, SCRIPTS and CREATE_SCRIPTS in the instance configuration file <bscw-runtime-path>/conf/config.py.

The localhost port to the HTTP server defined in HTTP_LOCAL_PORT must support HTTP; HTTPS is not supported!

The BSCW setup process automatically generates the following Apache HTTP server configuration files

<bscw-runtime-path>/conf/apache24/mod.conf
<bscw-runtime-path>/conf/apache24/site.conf
<bscw-runtime-path>/conf/apache24/bscw.conf

which contain all necessary configuration instructions.

The mod.conf file ensures the loading of additional modules required by BSCW and must be included in the main Apache HTTP server configuration file httpd.conf. Instead including this file you could enable the loading of the required modules

cgid_module (or cgi_module)

deflate_module

expires_module

headers_module

rewrite_module

ssl_module

proxy_module [1]

proxy_http_module [1]

Note

  • The suexec_module must be disabled.

Anyway the preferred mechanism of your Unix distribution should be used to enable the required modules:

  • Debian based systems:

    $ su -
# a2enmod cgid deflate expires headers rewrite ssl
# a2enmod proxy proxy_http # [1]
# a2dismod suexec
# systemctl restart apache2

  • EL based systems:

    $ su -
# vim /etc/httpd/conf.modules.d/00-base.conf     # EL
# vim /etc/httpd/conf.modules.d/00-proxy.conf    # [1]
# vim /etc/httpd/conf.modules.d/00-ssl.conf
# systemctl restart httpd

[1] Only required if the BSCW pre-forked HTTP server is used (see http for details).

The site.conf file contains several virtual host containers which can be used for Apache layouts which support site configuration file directories (e.g. Debian based systems /etc/apache2/sites-available/, EL based systems /etc/httpd/conf.d/).

Depending on your SERVER_ROOT definition in the instance configuration file <bscw-runtime-path>/conf/config.py, the site.conf file defines the following virtual hosts:

  1. if a HTTP server root is defined (e.g. the SERVER_ROOT directive starts with http://...) the site.conf file defines two virtual host containers: a first virtual host container for localhost:80 required by internal BSCW services and a second virtual host container for the server root host name <hostname>:80 for requests.
  2. if a HTTPS server root is defined (e.g. the SERVER_ROOT directive starts with https://...) the site.conf file defines three virtual host containers: a first virtual host container for localhost:80 required by internal BSCW services, a second virtual host container for the server root host name <hostname>:80 which redirects all requests to the third virtual host container <hostname>:443 for SSL requests.

Copy the site.conf file to your Apache HTTP server configuration. Please note it will most likely not work out of the box, but you have to adapt it to your local Apache HTTP server configuration. Especially you will need to install certificates for your SSL enabled server and adapt the configuration in site.conf.

The bscw.conf file contains the actual BSCW instance configuration for the Apache HTTP server. When using virtual web server container (<VirtualHost> ...  </VirtualHost>) directives, it is possible to include the <bscw-runtime-path>/conf/apache24/bscw.conf configuration file in multiple virtual web server containers. An example for a virtual web server definition in the Apache HTTP server configuration file should look as follows:

# Security Headers
<IfModule headers_module>
    Header set Referrer-Policy: "same-origin"
    Header set X-Content-Type-Options: "nosniff"
    Header set X-Frame-Options: "sameorigin"
</IfModule>
#ServerTokens Prod
#TraceEnable Off

<VirtualHost 127.0.0.1:80>
    ServerName  bscw.domain.org
    ServerAlias localhost
    ServerAdmin hostmaster@domain.org

    ErrorLog        logs/bscw_domain_org_error_log
    CustomLog       logs/bscw_domain_org_access_log common
    ScriptLog       logs/bscw_domain_org_error_log

    DocumentRoot "<bscw-path>/var/www"
    <Directory "<bscw-path>/var/www">
        options                     ExecCGI FollowSymLinks MultiViews
        AllowOverride               None
        DirectoryIndex              index.html default.htm
        LanguagePriority            en de es fr
        AddType                     text/html en de es fr
        ForceLanguagePriority       Fallback
        Require                     all granted
    </Directory>

    Include "<bscw-runtime-path>/conf/apache24/bscw.conf"
</VirtualHost>

<VirtualHost bscw.domain.org:80>
    ServerName      bscw.domain.org
    ServerAdmin     hostmaster@domain.org

    ErrorLog        logs/bscw_domain_org_error_log
    CustomLog       logs/bscw_domain_org_access_log common
    ScriptLog       logs/bscw_domain_org_error_log

    DocumentRoot "<bscw-path>/var/www"
    <Directory "<bscw-path>/var/www">
        Options                     ExecCGI FollowSymLinks MultiViews
        AllowOverride               None
        DirectoryIndex              index.html default.htm
        LanguagePriority            en de es fr
        AddType                     text/html en de es fr
        ForceLanguagePriority       Fallback
        Require                     all granted
    </Directory>

    Include        "<bscw-runtime-path>/conf/apache24/bscw.conf"
</VirtualHost>

To provide a SSL encrypted web site your virtual web server definition should look like (Note: additionally you will still require a HTTP web server on localhost as defined above).

# Security Headers
<IfModule headers_module>
    Header set Referrer-Policy: "same-origin"
    Header set X-Content-Type-Options: "nosniff"
    Header set X-Frame-Options: "sameorigin"
</IfModule>
#ServerTokens Prod
#TraceEnable Off

<VirtualHost bscw.domain.org:80>

    ServerName  bscw.domain.org
    ServerAdmin hostmaster@domain.org

    ErrorLog    logs/bscw_domain_org_error.log
    CustomLog   logs/bscw_domain_org_access_log common
    ScriptLog   logs/bscw_domain_org_script.log

    <IfModule alias_module>
        RedirectMatch permanent ^/(.*)$ https://bscw.domain.org/$1
    </IfModule>
</VirtualHost>

<VirtualHost bscw.domain.org:443>
    ServerName  bscw.domain.org
    ServerAdmin hostmaster@domain.org

    ErrorLog    logs/bscw_domain_org_error.log
    CustomLog   logs/bscw_domain_org_access_log common
    ScriptLog   logs/bscw_domain_org_script.log

    <IfModule headers_module>
        Header set Strict-Transport-Security: "max-age=31536000; includeSubDomains"
    </IfModule>

    DocumentRoot "<bscw-runtime-path>/var/www"
    <Directory "<bscw-runtime-path>/var/www">
        Options                     ExecCGI FollowSymLinks MultiViews
        AllowOverride               None
        DirectoryIndex              index.html default.htm
        LanguagePriority            en de es fr
        AddType                     text/html en de es fr
        ForceLanguagePriority       Fallback
        Require                     all granted
    </Directory>

    SSLEngine on
    SSLVerifyDepth 5

    #SSLCACertificateFile           conf/ssl/ca-bundle.crt
    #SSLCertificateChainFile        conf/ssl/bscw_domain_org_root.crt
    SSLCertificateKeyFile           conf/ssl/bscw_domain_org.key
    SSLCertificateFile              conf/ssl/bscw_domain_org.crt

    Include        "<bscw-runtime-path>/conf/apache24/bscw.conf"
</VirtualHost>

You may change the BSCW Apache HTTP server configuration file by using the bsadmin conf_apache script. To adapt the generated Apache configuration file to your local web server settings use one of the following options:

  • If no option is used bsadmin conf_apache tries to read the old option setting from bscw.conf (if exists). Use option -n or remove bscw.conf if you want to avoid this.

  • If option -r is used (requires rewrite module) the user credentials are passed that the authentication is handled by the BSCW server (this is the default case).

  • If option -a is used, BSCW allows to let the Apache HTTP server perform authentication.

  • If option -s is used the Apache HTTP server is configured for authentication via client certificates. This option includes the -r option and requires a SSL enabled server.

  • If option -o is used client certificates authentication optional. This option includes the -r option and requires a SSL enabled server.

  • Option -S enables the following HTTP security headers: X-Content-Type-Options, Referrer-Policy, Strict-Transport-Security. Please make sure to apply these changes from conf/apache24/site.conf to your current configuration.

  • If the -D or -E options are used the Apache HTTP server is configured to compress (gzip) BSCW resources (-D) or to cache resources due to a long time future expiry date (-E). These options require the deflate (-D) or the expires (-E) modules (these options are enabled by default).

  • Using -d (instead of -D) also enables compression for BSCW responses.

    Warning

    Compression and TLS encrypted connections may allow an information disclosure attack (for more information search for “breach” attacks).

Note

  • If you are running several BSCW instances in different virtual hosts you must configure for each BSCW instance a different HTTP_LOCAL_PORT number and you must extend the VirtualHost directives by these local IP addresses/port pairs.
  • It might be necessary to add an extra Listen 127.0.0.1:<HTTP_LOCAL_PORT> directive to the main Apache HTTP server configuration file.
  • The port, the script alias path and the script name may be changed by altering the configuration directives HTTP_LOCAL_PORT, SCRIPTS and CREATE_SCRIPTS in the instance configuration file (<bscw-runtime-path>/conf/config.py). After altering these directives bsadmin conf_apache must be run again.

Remember to always restart your Apache HTTP server whenever the bsadmin conf_apache script was run. Please note the following relations between HTTP server directives and the BSCW server instance configuration file <bscw-runtime-path>/conf/config.py variable settings:

  • the BSCW server instance SERVER_ROOT definition must correspond at least with one (virtual) server name (as specified in the ServerName directive), e.g.:

    SERVER_ROOT = 'https://bscw.domain.org/'
<=>
ServerName "bscw.domain.org"
Port 443

  • the BSCW server instance value for the BSCW_REALM variable corresponds with the setting of the HTTP servers AuthType and AuthName directives, e.g.:

    BSCW_REALM = 'BSCW Shared Workspace Server'
<=>
AuthType = Basic
AuthName = "BSCW Shared Workspace Server"

Otherwise problems with user authentication might occur: typically, users are asked twice for their passwords during registration or when switching user id.

3.4.2. BSCW instance configuration

You might skip the next parts of the configuration if you just upgraded your old BSCW server. The old configuration should be OK.

Local configuration details of your BSCW instance are held in the configuration file at <bscw-runtime-path>/conf/config.py (cf. section 5.2 conf/config.py). The minimum you need to do is to configure Section 1: MANDATORY server settings of this file:

  • The “server root” - the host name (and port) part of your BSCW servers URL - is specified in the variable SERVER_ROOT contains the absolute URL of your BSCW server and an optional port. If no port is specified the standard ports 80 (for HTTP) or 443 (for HTTPS) are assumed:

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

    A fully qualified host name is required as server name bscw.domain.org, in order to allow the BSCW server to resolve its name to an IP address SERVER_ROOT may not contain an IP address any more!). Ideally you define a host name/nickname (A/CNAME) in your DNS zone, which points to your BSCW server host, e.g.:

    server1.domain.org        A        1.2.3.4
server2.domain.org        A        1.2.3.5
bscw.domain.org       CNAME        server1.domain.org

    Proceeding this way a future migration of your BSCW server from server1 to server2 will keep the well known URL http://bscw.domain.org/ and your license will not be invalidated by the migration.

  • SERVER_ADMIN contains the valid email address of the server administrator, e.g.:

    SERVER_ADMIN = 'bscw@domain.org'

  • SERVER_ADMINS defines a list of BSCW users that have administrator rights, e.g.:

    SERVER_ADMINS = [ 'bscw-admin', 'YourName' ]

    You will most likely want to add your BSCW login name to SERVER_ADMINS to give yourself administrator rights (and maybe the login names of other BSCW users who should have administrator rights).

  • SMTP_HOST contains a host name or an IP-address of a mail host, that accepts mail posting by SMTP, e.g.:

    SMTP_HOST = 'mail.domain.org'

    The BSCW system can use the local mail transfer agent (MTA), such as sendmail to send email (e.g. registration invitations), which should be fine for most installations. However, it may be better if BSCW directly uses your smart mailhost via SMTP. In general we recommend to use SMTP_HOST rather than SENDMAIL.

    To do this, set the SMTP_HOST directive in <bscw-runtime-path>/conf/config.py to the IP address (or fully qualified domain name) of the machine that hosts your smart mailhost.

    Note

    If you you are using MS Exchange as MTA, you must explicitly allow the IP address of your BSCW server host to relay email.

3.4.3. Administrator account

After your BSCW instance is running you can log in with the administrator account registered during the setup process (mind login name and password are case sensitive!) by opening the URL:

http://bscw.domain.org/sec/bscw.cgi

Actually to gain administrator rights you have to login a second time with your password by opening [Options ‣ Admin]. If you open the URL http://bscw.domain.org/pub/, you get a BSCW overview which contains links to your BSCW instance.

Note

If you get an Error: Wrong group id during this steps the BSCW CGI scripts are not executed with the group ID bscw. This may happen because of the following reasons:

  1. The set-group-id bit of the BSCW CGI script is not set. In this case, please execute the following command in your BSCW instance directory:

    $ cd <bscw-runtime-path>
$ ./bin/bsadmin chkconfig

  2. You have installed BSCW on a file system that is mounted with the nosuid option. In this case you have to remount the file system without the nosuid option.

  3. Your operating system does not support the set-group-id bit for scripts (eg. Linux, BSD). In this case you have to compile a binary wrapper program and to reinstall the CGI scripts. Please ensure a C-compiler (cc, gcc) is available in the path and execute the following command in your BSCW instance directory again:

    $ cd <bscw-runtime-path>
$ ./bin/bsadmin chkconfig

3.4.4. De-Installation

To de-install BSCW perform the following manual steps:

  • Disable your BSCW startup procedure (see BSCW Startup for details).

  • Disable all BSCW related entries in the crontab (see Garbage Collection) and disable the backup procedure (Backup).

  • Stop your BSCW instance

    $ cd $HOME/srv/<bscw-runtime-dir>
$ ./bin/bsadmin stop

  • Next remove all instance data, e.g.

    $ cd $HOME/srv
rm -rf <bscw-runtime-dir>

    Note

    This step irrevocably destroys all user data!

  • Finally remove the related BSCW distribution library, e.g.

    $ cd $HOME/lib
rm -rf bscw-5.2.6-<rev>-py27

    Note

    You may only remove the BSCW distribution library if no existing other BSCW instance requires this particular BSCW revision!

3.5. Database Server Startup, Garbage Collection and Backup

All data of the BSCW server is held in the BSCW data store and handled through the BSCW database server. The BSCW database server is managed with the start_servers script, which is located in the BSCW instance <bscw-runtime-path>/bin directory:

  • to start up BSCW database server, use

    $ <bscw-runtime-path>/bin/start_servers

  • to stop BSCW database server, use

    $ <bscw-runtime-path>/bin/start_servers -k

  • to run the garbage collector, use

    $ <bscw-runtime-path>/bin/start_servers -gc

The state and errors of the BSCW database server are logged in the file <bscw-runtime-path>/var/log/bscw.log. We recommend that start_servers should be executed at system boot and start_servers -k at shut-down.

3.5.1. BSCW Startup

First install the static configuration scripts in the according directory for your system. E.g. for Debian copy the files

$ sudo su -
# id
uid=0(root) gid=0(root) groups=0(root)
# cd /opt/bscw/lib/bscw-5.2.6-<rev>-py27/etc/posix/debian
# cp ./etc/default/bscw /etc/default
# cp ./etc/cron.daily/bscw /etc/cron.daily
# cp ./etc/cron.hourly/bscw_cleantmp /etc/cron.hourly
# cp ./etc/logrotate.d/bscw /etc/logrotate.d
# chmod 755 /etc/cron.daily/bscw /etc/cron.hourly/bscw_cleantmp

to the /etc directory. Afterwards edit the /etc/default/bscw (on Debian) resp. /etc/sysconfig/bscw (on EL) and /etc/logrotate.d/bscw files to adopt the BSCW user and the paths to your BSCW instances runtime directories.

To create a systemd service configuration run bsadmin conf_systemd and follow the given instructions:

$ bin/bsadmin conf_systemd

A systemd multiple instance service file ::

    bscw@.service

has been created. Please check the contents and perform the following
commands as root user: ::

    $ sudo su -
    # id
    uid=0(root) gid=0(root) groups=0(root)
    # cd /opt/bscw/srv/<bscw-instance-name>
    # cp ./conf/systemd/system/bscw@.service \
         /etc/systemd/system
    # systemctl daemon-reload
    # systemctl enable bscw@<bscw-instance-name>.service

3.5.2. Garbage Collection

You will need to set up the system to garbage collect every day. The task of the garbage collector is to find unreferenced, e.g., obsolete objects in the data store and remove them. For performance reasons, a delete operation on an object may not remove the respective object physically from the store. If you do not run the garbage collector periodically, the BSCW data store will grow constantly although many of its objects are obsolete. This would waste disk space and may substantially reduce the performance of the BSCW server.

We recommend that you set up a cron job for running the start_servers -gc script, though you can do it manually. An example crontab entry for daily garbage collection at 06:05 looks like:

# garbage collection
5 6 * * * <bscw-runtime-path>/bin/start_servers -gc

Do not stop the BSCW database server before garbage collection, the garbage collection needs a running server!

3.5.3. Backup

Additionally it is urgently recommended to have regular BACKUPS (e.g. daily) of the configuration and the data store to avoid loss of data, e.g., because of a disk crash. The recommended time for backup is just after garbage collection.

The garbage collection creates alternating a garbage collected version of the BSCW database in the files <bscw-runtime-path>/var/data/StoreA or StoreB.

Note

These locations can be overridden by editing <bscw-runtime-path>/conf/config.py.

Generally you should consider the following files or directories of your BSCW instance (relative to your <bscw-runtime-path>) for backup:

  • BSCW instance configuration files located in the ./conf/ directory

  • BSCW instance data files and directories such as

    ./var/data/
./var/log/
./var/www/

Best you backup your complete BSCW instance directory <bscw-runtime-path>.

Note

  • The var/data/Text and var/data/Index directories may be skipped while backup, because the contents may be reconstructed after restoration of a backup.
  • You can use any incremental backup method to backup your BSCW instance

3.6. Folder Mail Delivery

Sending email to a BSCW folder is an alternative to the usual HTML/HTTP interface where users create content, e.g., via [Add Document] or [Add Note] actions using a Web browser. To enable folder mail delivery the following configuration steps have to take part:

  • the BSCW mail delivery agent (MDA) has to be configured
  • the local mail transfer agent (MTA) mail has to be configured to deliver incoming mails for the BSCW server mailbox to the BSCW MDA

Note

Your MTA must support VERP (variable envelope return paths) to allow the individual addressing of single folders; BSCW folder delivery is known to work with recent versions of Postfix or sendmail).

3.6.1. BSCW mail delivery agent (MDA)

The BSCW mail delivery agent (MDA) is configured by setting the following entries in the BSCW server instance configuration file <bscw-runtime-path>/conf/config.py:

#  MDA_MTA
#    Specifies the local mail transfer agent (MTA), currently
#    supported are:
#    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
#    Local mailbox name for BSCW mda (this is normally the BSCW
#    user id name)
#  MDA_DOMAIN
#    Domain name of the BSCW MDA (which is the delivery domain of
#    the local MTA for the local BSCW MDA mailbox)
#  MDA_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']
#  MDA_EXTRACTMAIL
#    if MDA_EXTRACTMAIL evaluates to True, in 'mailaccess' form
#    a preselcted option "[x] extract emails into a folder" is shown
#  MDA_DELIMITER = None (optional)
#    allows to override the MTA default recipient delimiter
#    MDA_DELIMITER = '+' (sendmail/postfix)
#  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 = 'postfix'
MDA_MBOX = 'lab'
MDA_DOMAIN = 'bscw.de'
MDA_HDRMETA = ['RFC822:from', 'RFC822:to', 'RFC822:cc']
MDA_EXTRACTMAIL = False

In the given example, the local BSCW mailbox is set to lab and the delivery domain name of the local MTA is bscw.de. Hence, a folder mail address has the form lab+1234@bscw.de (for sendmail and postfix).

To ensure consistent mail addresses, when local BSCW mail delivery is enabled, the BSCW server should only use the local mail server, therefore it is advisable to set

SMTP_HOST = ''

3.6.2. Local Mail Transfer Agent (MTA)

To deliver mail into a BSCW folder the localhost mail transfer agent has to deliver mail messages to a “program”, namely to the BSCW mail deliver agent. This is achieved by “piping” the message into the BSCW main CGI script:

"|<bscw-runtime-path>/var/www/bscw.cgi"

3.6.2.1. Postfix

To enable the BSCW MDA to deliver mails into folders for the Postfix MTA add the line

recipient_delimiter = +

to the Postfix configuration file /etc/postfix/main.cf.

After Postfix configuration, the program delivery to the BSCW MDA is enabled by choosing one of the following alternatives:

  • enter the following line into BSCW users ID $HOME/.forward file:

    "|<bscw-runtime-path>/var/www/bscw.cgi"

    or

  • add an alias for the MDA_MBOX (e.g. bscw) directive to the sendmail aliases database /etc/aliases file:

    bscw:       "|<bscw-runtime-path>/var/www/bscw.cgi"

    and run the newaliases program.

Finally to enable folder mail delivery in BSCW set in the BSCW server instance configuration file <bscw-runtime-path>/conf/config.py (beside the other settings described above)

MDA_MTA = 'postfix'

Note

When using Python < 3.7 the delivery of mails with unicode characters in the subject fails. To workaround this set LANG=en_US.UTF-8 within the postfix import_environment parameter in the Postfix configuration file /etc/postfix/main.cf, e.g.:

$ su -
# postconf -d import_environment
import_environment = MAIL_CONFIG MAIL_DEBUG MAIL_LOGTAG TZ XAUTHORITY DISPLAY LANG=C
# add to /etc/postfix/main.cf:
import_environment = MAIL_CONFIG MAIL_DEBUG MAIL_LOGTAG TZ XAUTHORITY DISPLAY LANG=en_US.UTF-8

To test the folder mail delivery create a folder (within BSCW) and trigger the action “Open to Mail”. Choose in the form the “enabled for anybody” option. After enabling the mail upload look at the folders info page to determine the folders email address. (If in the “Details” table a “Email address” row is missing, the BSCW MDA was not properly configured, check again your BSCW MDA configuration).

To debug the mail delivery enter the following entry into the BSCW_LOGGING directive in the BSCW server instance configuration file <bscw-runtime-path>/conf/config.py:

BSCW_LOGGING = {
    'mda': ('DEBUG', 'mda.log'),
}

Send a mail message to the prepared folder address and check in file:/var/log/syslog (or wherever your postfix MTA writes its log entries) if the local postfix MTA received the message and delivered it to the BSCW MDA. Typical log entries of a successful delivery look like:

Nov 15 15:29:18 hosting-b24d7f41 postfix/smtpd[27822]: 786AD18660BA:
    client=localhost[127.0.0.1]
Nov 15 15:29:18 hosting-b24d7f41 postfix/cleanup[27823]: 786AD18660BA:
    message-id=<2018111542916.GA10103@orbigate.orbiteam.de>
Nov 15 15:29:18 hosting-b24d7f41 postfix/smtpd[27822]:
    disconnect from localhost[127.0.0.1]
Nov 15 15:29:18 hosting-b24d7f41 postfix/qmgr[2714]: 786AD18660BA:
    from=<paulsen@orbiteam.de>, size=1791, nrcpt=1 (queue active)
...
Nov 15 15:29:18 hosting-b24d7f41 postfix/local[27841]: 786AD18660BA:
    to=<lab+1234@mail.orbiteam.de>, relay=local, delay=0.38,
    delays=0.01/0.01/0/0.36, dsn=2.0.0, status=sent (delivered to command:
    /opt/bscw/srv/lab.bscw.de/var/www/bscw.cgi)
Nov 15 15:29:18 hosting-b24d7f41 postfix/qmgr[2714]: 786AD18660BA: removed

Next check the log file (default: <bscw-runtime-path>/var/log/mda.log). A successful delivery log entry for a postfix MTA looks like:

2020-11-15 15:29:18 mda    INFO    invoked as 523/57
2020-11-15 15:29:18 mda    DEBUG
    MDA_MTA    = 'postfix'
    MDA_MBOX   = 'lab'
    MDA_DOMAIN = 'bscw.de'
2020-11-15 15:29:18 mda    INFO    start delivery
2020-11-15 15:29:18 mda    INFO    sender addr in 'from': header.
2020-11-15 15:29:18 mda    INFO    recipient in header: <lab+1234@bscw.de>
2020-11-15 15:29:18 mda    INFO    set domain to 'bscw.de'
2020-11-15 15:29:18 mda    INFO    store document
2020-11-15 15:29:18 mda    INFO    message loaded
2020-11-15 15:29:18 mda    INFO    message stored size=2028
2020-11-15 15:29:18 mda    INFO    virus check OK
2020-11-15 15:29:18 mda    INFO    msg for Folder#118433 (access 'anybody');
2020-11-15 15:29:18 mda    INFO    msg from info <info@orbiteam.de> delivered.

3.6.2.2. Sendmail

To enable the BSCW MDA to deliver mails into folder for sendmail the following /etc/mail/sendmail.cf configuration must be ensured:

  • to allow sendmail program message delivery to the BSCW MDA the sendmail “prog” mailer has to be defined in /etc/mail/sendmail.cf as follows:

    Mprog,    P=/bin/sh, F=lsDFMPoqeu9,
          S=EnvFromL/HdrFromL, R=EnvToL/HdrToL, D=$z:/,
          T=X-Unix/X-Unix/X-Unix,
          A=sh -c $u

    The F and P flags in the “prog” mailer flag list F= are required, to ensure the message contains a From: and Return-Path: header line.

    Note

    you may not use smrsh (restricted shell for sendmail) as “prog” mailer for sendmail, since it does not permit the delivery into the BSCW MDA script. Alternatively you might link the bscw.cgi script from /etc/smrsh.

  • to enable the BSCW MDA to determine a well-defined recipient of a message you have to ensure the header definition HReceived in /etc/mail/sendmail.cf contains a

    for $u; $|;

    line (which is the default setting in newer sendmail versions).

  • To make multiple recipients work with sendmail add a Delivered-To: header by enter the following configuration line to /etc/mail/sendmail.cf:

    H?J?Delivered-To: $u

After editing /etc/mail/sendmail.cf your sendmail needs to be restarted before changes become effective.

After successful sendmail configuration, the program delivery to the BSCW MDA is enabled by choosing one of the following alternatives:

  • enter the following line into BSCW users ID $HOME/.forward file:

    "|<bscw-runtime-path>/var/www/bscw.cgi"

    or

  • add an alias to the sendmail aliases database /etc/aliases file

    bscw:   "|<bscw-runtime-path>/var/www/bscw.cgi"

and run the newaliases program.

Finally to enable folder mail delivery in BSCW set in the BSCW server instance configuration file <bscw-runtime-path>/conf/config.py (beside the other settings described above)

MDA_MTA = 'sendmail'

To test the folder mail delivery create a folder (within BSCW) and trigger the action “Open to Mail”. Choose in the form the “enabled for anybody” option. After enabling the mail upload look at the folders info page to determine the folders email address. (If in the “Details” table a “Email address” row is missing, the BSCW MDA was not properly configured, check again your BSCW MDA configuration).

To debug the mail delivery enter the following entry into the BSCW_LOGGING directive in the BSCW server instance configuration file <bscw-runtime-path>/conf/config.py:

BSCW_LOGGING = {
    'mda': ('DEBUG', 'mda.log'),
}

Send a mail message to the prepared folder address and check in /var/log/syslog (or wherever your sendmail writes its log entries) if the local sendmail program received the message and delivered it to the BSCW MDA. Typical log entries of a successful delivery look like:

Nov 15 15:29:17 maestral sendmail[5801]: g97G0Kp05801:
    from=<info@orbiteam.de>, size=551, class=0, nrcpts=1,
    msgid=<201811151600.g97G0DW08799@tormenta.orbiteam.de>,
    proto=ESMTP, daemon=MTA-IPv4, relay=mail [195.127.160.172]
Nov 15 15:29:17 maestral sendmail[5802]: g97G0Kp05801:
    to=|/opt/bscw/srv/lab.bscw.de/var/www/bscw.cgi,
    ctladdr=<lab+1234@bscw.de> (523/57), delay=00:00:01,
    xdelay=00:00:00, mailer=prog, pri=30015, dsn=2.0.0, stat=Sent

Next check the log file (default: <bscw-runtime-path>/var/log/mda.log). A successful delivery log entry for a sendmail MTA looks like:

2020-11-15 15:29:18 mda    INFO    invoked as 523/57
2020-11-15 15:29:18 mda    DEBUG
    MDA_MTA    = 'sendmail'
    MDA_MBOX   = 'lab'
    MDA_DOMAIN = 'bscw.de'
2020-11-15 15:29:18 mda    INFO    start delivery
2020-11-15 15:29:18 mda    INFO    sender addr in 'from': header.
2020-11-15 15:29:18 mda    INFO    recipient in header: <lab+1234@bscw.de>
2020-11-15 15:29:18 mda    INFO    set domain to 'bscw.de'
2020-11-15 15:29:18 mda    INFO    store document
2020-11-15 15:29:18 mda    INFO    message loaded
2020-11-15 15:29:18 mda    INFO    message stored size=2028
2020-11-15 15:29:18 mda    INFO    virus check OK
2020-11-15 15:29:18 mda    INFO    msg for Folder#118433 (access 'anybody');
2020-11-15 15:29:18 mda    INFO    msg from info <info@orbiteam.de> delivered.