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.2.

3.1. System requirements

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

  • Intel Core/Xeon or AMD A-series/Opteron (>3,2 GHz) 64-bit server system with at least 4 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:

  • 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.
  • Alternatively download, compile and install the required software from the project web sites, e.g. the Apache HTTP server (http://httpd.apache.org/) or Python 2.7 (http://www.python.org).

Note

  • On Fedora based systems you need to add the EPEL repository, see https://fedoraproject.org/wiki/EPEL for details.
  • 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.
  • BSCW needs the Python module crypt. This module is not always installed by default. In this case you have to enable the crypt module in Modules/Setup and rebuild Python.

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, Python, the desired Python extension packages and the converter software are installed.

On Linux systems it is recommended to use a Debian or a 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
  • Fedora based systems: httpd python 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.?-???????-py27.tar.gz

The name of the download file contains BSCW and Python version numbers – e.g. bscw-5.2.?-???????-py27.tar.gz contains BSCW version 5.2.2 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).

Ensure to disable the SELinux extension (which is enabled by default on Fedora 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:

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

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

/home/bscw/lib/                              # BSCW distribution libraries
/home/bscw/lib/bscw-5.2.?-???????-py27/      # BSCW distribution 5.2.?
/home/bscw/lib/bscw-5.2.?-???????-py27/bin
/home/bscw/lib/bscw-5.2.?-???????-py27/bscw  # BSCW executable code
/home/bscw/lib/bscw-5.2.?-???????-py27/doc   # BSCW documentation
/home/bscw/lib/bscw-5.2.?-???????-py27/etc
/home/bscw/lib/bscw-5.2.?-???????-py27/lib   # BSCW third party modules

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

The BSCW layout allows to install multiple BSCW instances in the runtime directory /home/bscw/srv, which all share the same BSCW program code located in the library directory /home/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 /home/bscw. If no BSCW user is found a new BSCW system user bscw with an own group bscw and a home directory /home/bscw is proposed and then created.

Note

  • /home/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 /home/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.?-???????-py27.tar.gz
# cd bscw-5.2.?-???????-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.?-???????-py27.tar.gz
    $ cd $HOME/lib
    $ tar xf /tmp/bscw-5.2.?-???????-py27/bscw-5.2.?-???????-py27.tar
    
  • run the installation procedure setup.py <bscw-runtime-path> and follow the instructions

    $ cd $HOME/lib/bscw-5.2.?-???????-py27
    $ python2.7 ./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: [/home/bscw]

Enter BSCW base directory: [/home/bscw]

Extracting BSCW 5.2.? distribution in /home/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
/home/bscw/srv
the default [bscw.domain.org] is created):

BSCW instance name: [bscw.domain.org]
target '/home/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
'/home/bscw/srv/bscw.domain.org/conf/__init__.py' updated
no config_run.pyc yet
Import core modules ...
Import modules for portal ...
Import modules for airdesktop ...
Import modules for approval ...
Import modules for blog ...
Import modules for case ...
Import modules for FlowFolder ...
Import modules for metaprofiles ...
Import modules for microblog ...
Import modules for mobile ...
Import modules for poll ...
Import modules for rss ...
Import modules for sync ...
Import modules for Tasks ...
Import modules for WebFolder ...
Link destination '/home/bscw/lib/bscw-5.2.?-???????-py27/extensions' does not exist
config_convert.py created
bsadmin update_defaults
bsadmin manage_servers -u
2017-08-28 09:28:46 bsadmin chkconfig -check-access
2017-08-28 09:28:46 access checks...
cc -o var/run/run_bscw var/run/run_bscw.c
2017-08-28 09:28:46 Actual license: OK (none)
2017-08-28 09:28:46 bsadmin start
2017-08-28 09:28:47 bsadmin garbage -license
2017-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:   20170427
                    Evaluation licence max users: 200
[...]
bsadmin convert -check-access
Configure 'gzip' compression ...
Configure 'static' resources '/home/bscw/lib/bscw-5.2.?-???????-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
/home/bscw/srv/bscw.domain.org/conf/apache24
   mod.conf ... module configuration file
  site.conf ... virtual host site configuration file
  bscw.conf ... BSCW configuration file
bsadmin conf_apache
bsadmin index_page
register admin user
user admin registered, address:
    admin@domain.org: (is_owned_by_user)

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

BSCW instance created: '/home/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
/home/bscw/lib/bscw-5.2.?-???????-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 8 (http://www.oracle.com/technetwork/java)

    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
      • Fedora based systems: java-1.8.0-openjdk
  2. PhantomJS 2.1 (http://phantomjs.org/)

    PhantomJS is a headless WebKit scriptable with a JavaScript API and can be downloaded from:

    http://phantomjs.org/download.html
    
    • 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

  3. 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
      • Fedora based systems: ghostscript ghostscript-fonts
  4. 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
      • Fedora 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
      
  5. LibreOffice (https://www.libreoffice.org/)

    LibreOffice is a open source office suite

    Note

    At least LibreOffice version 5 is required, best use the current release LibreOffice 6.0 or 6.1

    • The LibreOffice version of the distribution should be installed.

      Packages name(s) for common Linux distributions:

      • Debian based systems: libreoffice python3-uno
      • Fedora based systems: libreoffice libreoffice-pyuno
    • For better conversion results install the Microsoft TrueType core fonts

      • Debian based systems: ttf-mscorefonts-installer
      • Fedora based systems: see http://mscorefonts2.sourceforge.net/
    • 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:www-data /var/www
        
      • Fedora based systems:

        $ su -
        # chown apache:apache /usr/share/httpd  # EL 7
        

    Attention

    Be sure the Python UNO bridge is installed!

  6. Text/HTML converter

    Install the markdown2 and html2text converters as follows:

    • markdown2 converts text to HTML using the markdown markup

      Packages name(s) for common Linux distributions:

      • Debian based systems: python-pip
      • Fedora based systems: python-pip

      Since no distribution packet exists, use pip 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
      • Fedora 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
      
  7. Image converter

    For image conversion the Python Imaging Library is required

    Packages name(s) for common Linux distributions:

    • Debian based systems: python-pil
    • Fedora based systems: python-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 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

    and copy it into the BSCW distribution

    $ cd $HOME/lib/bscw-5.2.?-???????-py27
    $ cp tika-server-1.??.jar bscw/libexec/tika
    $ chmod 644 bscw/libexec/tika/tika-server-1.??.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:

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

indicates that the ghostscript standard fonts are missing resp. are not properly installed.

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 following additional modules required by BSCW are loaded and may be included in the main Apache HTTP server configuration file:

cgid_module (or cgi_module)

deflate_module

expires_module

headers_module

rewrite_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
    
  • Fedora based systems:

    $ su -
    # vim /etc/httpd/conf.modules.d/00-base.conf     # RHEL 7
    # 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/, Fedora 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.

Both files include the bscw.conf file with the actual BSCW instance configuration. If you intend to use the site.conf file copy it 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. It may be included in the main configuration file if you manually define virtual hosts (within the standard Apache HTTP server layout) or in the main HTTP server configuration file without defining virtual hosts:

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

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:

<VirtualHost bscw.domain.org: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).

<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

    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.

  • 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 the -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.

    Note

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

  • 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.?-???????-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

The BSCW distribution provides static SysV init scripts for several Unix distributions. Since Fedora 15 introduced systemd, which is adapted by many Linux distributions (such as Debian >= 8), alternatively BSCW supports a systemd service configuration (bsadmin conf_systemd) for the current BSCW instance. Preferably use on systems with systemd support the native BSCW systemd service configuration prior to the provided static SysV init scripts.

You will find static configuration scripts in the according directory for your system. E.g. for Debian Linux copy the files

$ sudo su -
# id
uid=0(root) gid=0(root) groups=0(root)
# cd /home/bscw/lib/bscw-5.2.?-???????-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 according /etc directory. Afterwards edit the files an adopt the paths to your installation.

Next choose one of the following options:

  1. 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 /home/bscw/srv/<bscw-instance-name>
        # cp ./conf/systemd/system/bscw@.service \
            /etc/systemd/system
        # systemctl daemon-reload
        # systemctl enable bscw@<bscw-instance-name>.service
        # systemctl start bscw@<bscw-instance-name>.service
    

    OR

  2. To enable the old style init script copy the provided SysV init script to /etc/init.d/bscw, for example on Debian (< 8) systems:

    $ sudo su -
    # id
    uid=0(root) gid=0(root) groups=0(root)
    # cd /home/bscw/lib/bscw-5.2.?-???????-py27/etc/posix/debian
    # cp ./etc/default/bscw /etc/default
    # cp ./etc/init.d/bscw /etc/init.d
    # chmod 755 /etc/init.d/bscw
    

    Next edit the /etc/default/bscw file to set your BSCW user and the paths to your BSCW instances runtime directories. Finally you have to enable the bscw init script for the different run-levels. Refer the boot script comments how to obtain this for your system, for example on Debian:

    On Debian based systems before Debian 8 / Ubuntu 14.04 copy this
    script to '/etc/init.d' and run
      1) Debian / Ubuntu (with systemd)
          systemctl enable bscw
      2) Debian / Ubuntu (SysV init)
          update-rc.d bscw defaults
          update-rc.d bscw enable
    

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 sendmail, Postfix or qmail).

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 = '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
#    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_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 = '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) and lab-1234@bscw.de (for qmail).

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. 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=<201705151600.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=|/home/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:

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

3.6.2.2. 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'

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=<20170301142916.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:
    /home/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:

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

3.6.2.3. Qmail

To assign a local BSCW user mailbox, enter the following lines into your /var/qmail/users/assign file

=<bscw-mbox>:<bscw-user>:<bscw-uid>:<bscw-gid>:<bscw-runtime-path>:::

+<bscw-mbox>-:<bscw-user>:<bscw-uid>:<bscw-gid>:<bscw-runtime-path>:-::

where

<bscw-mbox> = local BSCW server mailbox as defined in MDA_MBOX, e.g. lab

<bscw-user> = user name of the BSCW server user, e.g. bscw

<bscw-uid> = user ID of the BSCW server user, e.g. 523

<bscw-gid> = group ID of the BSCW server user, e.g. 523

<bscw-runtime-path> = path to your BSCW instance, e.g. /home/bscw/srv/lab.bscw.de

While the configuration line starting with a = character defines the handling of the local address bscw, the line starting with a + character handles all extension addresses bscw-* (for further details consult the qmail-users man page or the “Life with qmail” documentation). After changing the contents of the /var/qmail/users/assign file you have to run the qmail-newu command to update the assignments database.

To enable BSCW MDA program delivery for all extension addresses bscw-*, create the file <bscw-runtime-path>/.qmail-default (with the BSCW user ID and group ID as owner) and enter one single line:

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

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

MDA_MTA = 'qmail'

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 in the BSCW server instance 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 qmail-send writes its log entries). If the qmail-send program delivered it to the BSCW MDA. Typical (sys)log entries of a successful delivery look like:

Nov 15 15:29:18 maestral qmail: [ID 748625 mail.info] 1029764356.914769
    info msg 236165: bytes 653 from <info@orbiteam.de> qp 4281 uid 503
Nov 15 15:29:18 maestral qmail: [ID 748625 mail.info] 1029764356.915894
    starting delivery 22: msg 236165 to local lab-1234@bscw.de
Nov 15 15:29:18 maestral qmail: [ID 748625 mail.info] 1029764356.916318
    status: local 1/10 remote 0/20
Nov 15 15:29:18 maestral qmail: [ID 748625 mail.info] 1029764357.554749
    delivery 22: success: did_0+0+1/
Nov 15 15:29:18 maestral qmail: [ID 748625 mail.info] 1029764357.555183
    status: local 0/10 remote 0/20
Nov 15 15:29:18 maestral qmail: [ID 748625 mail.info] 1029764357.555524
    end msg 236165

Check the log file (default: <bscw-runtime-path>/data/mda.log). A successful delivery log entry for a qmail MTA looks like:

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