Bluewhale ApS
Fruebjergvej 3, boks 1
DK-2100 Copenhagen Ø

Phone: +45 39 17 99 73
CVR: DK29824479

Bluewhale Server Support


Bluewhale Server installation
Running Bluewhale for the first time

Additional configuration

Adding and removing users
Firewall configuration
LDAP configuration
Kerberos/single sign-on configuration
Antivirus configuration
SSL configuration
Two-factor download authentication

Bluewhale Server installation

This section describes the quickest way to get Bluewhale Server up and running.
For production environments additional steps should be considered; e.g. firewall configuration, LDAP/Kerberos integration, antivirus and SSL configuration.


1. Download Bluewhale Server

Go to
Download Bluewhale Server for Windows and save it on your computer.

2. Run the installer

Double click on "bwserver_windows_3_0_1.exe".
If Windows shows a "Open File - Security Warning" just click "Run".

Select the folder where you want to install Bluewhale Server and click "Next".

3. Configure Bluewhale Server


Select the folder where you want Bluewhale Server to store the files sent by the users (Bluewhale datastore).

Enter your outgoing SMTP mail server.
Important: The mail server must accept and relay mail from the Bluewhale Server.
This is usually done by adding the IP address of the machine where you install Bluewhale Server to the mail server's list of trusted IPs.

Enter the public URL of the Bluewhale Server.
Important: You must add a DNS record to your domain with the choosen name, otherwise users will be unable to connect to the server.

Enter the desired port numbers of the Bluewhale Server. Unless you are already running a web server on the same machine, you should keep the default port numbers.

Enter the desired Bluewhale administrator password twice.

Enter your license key.
You can obtain a license key by requesting a free trial

Click "Next".

4. Configure your first Bluewhale user


Enter the user's e-mail address and the desired password twice.

Click "Next".

Click "Finish".

Your Bluewhale Server is now ready for use.

A browser should now open automatically and show the Bluewhale Server welcome page.

You can also open the Bluewhale Server welcome page from the Start menu by selecting:
"All Programs" > "Bluewhale Server" > "Bluewhale Server".

In case of any problems, please consult the server logs which can be found in the log folder, e.g.:

C:\Program Files\Bluewhale Server\logs

Running Bluewhale for the first time

Bluewhale browser client

On the Bluewhale Server welcome page enter the e-mail address and the password of the user you created during the installation. Then click on the "Login"-button.

You are now ready to send large files (up to 1 Gb) using the Bluewhale browser client.

Just enter the recipient e-mail, choose a file and click "Send".

Bluewhale Desktop (Java Webstart)

From the Bluewhale Server welcome page choose "Start Bluewhale".

Your browser may prevent Bluewhale Desktop from starting. In that case just select "Download File...".

On the login screen enter the e-mail address and the password of the user you created during the installation. Then click on the "Login"-button.

You are now ready to send large files and folders (up to 4 Gb) from Bluewhale Desktop.

More about Bluewhale Desktop...

Bluewhale for Outlook

Go to
Download Bluewhale for Outlook and save it on your computer.

Make sure that Outlook is not running.
If you downloaded the the zip-file, unzip "" and run "Setup.exe" (requires Administrative rights).
If you downloaded the msi-file, just double click to install (requires Administrative rights).

If you are installing on Windows Vista or Windows 7, you must start the installation from an Administrator Command Prompt (right click on "Command Prompt" and select "Run as Administrator").

When the installation has finished start Outlook and click on the Bluewhale icon in the toolbar.
In the Bluewhale server field enter the URL to the Bluewhale Server, e.g.:
"" or "http://localhost" if you have installed Bluewhale Server on your own workstation.

Login: <first user e-mail>
Password: <first user password>

Click "Test login" to verify the settings.
If the test is successful click "OK" to the save the settings.

You are now ready to send large files and folders (up to 4 Gb) from Outlook.

More about Bluewhale for Outlook...

Adding and removing users

By default, Bluewhale will validate users against its internal user database.
If LDAP integration is enabled, valid LDAP users are automatically created in Bluewhale Server the first time they use Bluewhale.

When running without LDAP integration new users must be created manually:
From the Bluewhale Server welcome page select "Administrator login".

Login: admin
Password: <the password you entered when installing>

To edit an existing user first click the "Search" button and then click "Edit" on the user you wish to edit.

To create a new user click "Create new account".

Enter the user name, e-mail, login and password and click "Save".

Firewall configuration

Bluewhale transfers data via HTTP or HTTPS. This ensures very broad firewall compatibility. When installing Bluewhale Server it is recommended to use the standard ports (80 and 443) for maximum compatibility with remote users' firewalls.

To enable people from the outside of your network to download Bluewhale attachments, you must open the appropriate ports in your firewall (i.e. 80 or 443) and map your public assigned IP to the internal IP of the Bluewhale Server. This is usually done in the firewall/router configuration.

On the Bluewhale Settings page the Host URL must be updated with the public hostname of your server, e.g.

LDAP configuration

Bluewhale can validate users against its own user database or against a LDAP directory.

It is highly recommended to enable SSL when using LDAP. Otherwise, passwords are sent across the network in clear text.

LDAP Configuration

If you check Require Group, there must be a group in AD called Bluewhale. the members of the Bluewhale group

is granted access to a bluewhale account.

To enable LDAP check the LDAP login field and enter the LDAP URL.
For Windows domain controllers use port 3268 for the global catalog, e.g.:


Replace the IP address with the IP address or server name of your LDAP server.

You also need to provide a domain login which is valid for LDAP queries and the default domain, e.g.:

    Login: bwservice
Password: *********
Default domain: COMPANY.LOCAL

You can verify the LDAP settings by clicking the Test button.

For nested AD groups, the DN (ie full distinctive name) will be extracted from the AD Group account in “LDAP Group”, and placed in “LDAP Group DN”

By setting the search base you can limit the access to Bluewhale within your organization, e.g.:


allows users on the domain to use Bluewhale.

If you wish to allow users to login using their e-mail address, type in your e-mail domain, e.g., and your login domain, e.g. company.local. When both fields are specified the system will replace e-mail domain with the login domain prior to passing logins to the LDAP server.

When LDAP integration is enabled Bluewhale will use the "mail" attribute as e-mail address.
If LDAP names is enabled Bluewhale will use the "displayName" attribute as name. If displayName is empty Bluewhale will use the "givenName" and "sn" attributes.

Kerberos/single sign-on configuration

Please follow the steps below to enable the single sign-on feature in Bluewhale for Outlook.

Please notice that Kerberos requires LDAP to be enabled and your firewall must allow Bluewhale Server to connect to the KDC (domain controller) on port 88/tcp and udp.

On Windows 2008 (r2) the setspn.exe and ktpass.exe commands are installed by default.

If you are installing on Windows 2003 (r2) the setspn.exe and ktpass.exe are a part of the Windows Support Tools which are available on your Windows Server 2003 installation media.
Notice that there is a known bug in the Windows Server 2003 SP1 version of ktpass.exe, so please check that your ktpass.exe has file version 5.2.3790.2732 or newer.

*Please note that Kerberos realm name must be upper case regardless of the casing used in your domain name. 

1. Create service account

Create a Bluewhale service account in Active Directory, e.g. "bwservice".
Uncheck "User must change password at next logon".
Check "Password never expires".

2. Map SPN

Map a Kerberos service principal (SPN) to the new account.
On the DC -
Open a command prompt and type:

setspn -a bluewhale/ bwservice                    

Replace "" with the DNS name of your Bluewhale Server.
Replace "COMPANY.LOCAL" * with the name of your domain.
Replace "bwservice" with the name of the account you created.

3. Create keytab

Create a keytab file, Windows 2008 (r2):
On the DC -
Open a command prompt and type (One line):

 ktpass -out bwservice.keytab -princ bluewhale/

 -mapUser DOMAIN\bwservice -mapOp set -pass PASSWORD -crypto All -ptype KRB5_NT_PRINCIPAL

Please notice that the Windows 2008 (r2) version of ktpass supports the "-crypto All" option, which generates keys for all supported encryption algorithms. On Windows 2008 (r2) DES encryption is not enabled by default. Kerberos communication with the Bluewhale Server will be encrypted using the more secure "aes128-cts-hmac-sha1-96" (etype 17).

When generating the keytab file without the +DesOnly option, please be sure that "Use DES encryption" is not checked for the bwservice account on the Account tab in Active Directory Users and Computers.

Create a keytab file, Windows 2003 (r2):

ktpass -out bwservice.keytab -princ bluewhale/
-mapUser DOMAIN\bwservice -mapOp set -pass PASSWORD -crypto DES-CBC-MD5 +DesOnly

Replace "bluewhale/" with the SPN you created above.
Replace DOMAIN\bwservice with the account you created in 1.
Replace PASSWORD with a proper password.

Copy the keytab file from where you created it to the Bluewhale Server installation directory, e.g.:
C:\Program Files\Bluewhale Server\

4. Edit the Kerberos configuration file.

Edit the kerberos.conf file in the Bluewhale Server installation directory: { required
useKeyTab=true keyTab=bwservice.keytab
storeKey=true principal="bluewhale/"

Replace "bluewhale/" with your SPN.

5. Update Bluewhale Server settings

From the Bluewhale Server welcome page select "Administrator login". Choose Settings.

Check "Kerberos Login".
Enter realm (domain), KDC (domain controller) and SPN.
Finally enter the path to the Kerberos configuration file, e.g.:
C:\Program Files\Bluewhale Server\kerberos.conf

Please notice that specifying "localhost" as KDC will not work, you must use the DNS name, even if you are installing Bluewhale Server on the same machine.

You can verify the Kerberos settings by clicking the "Test login" button.

6. Configure Bluewhale for Outlook

To enable the single sign-on feature in Bluewhale for Outlook, you must set enter the SPN and select "Use Windows Integration Security".
The computer where Bluewhale for Outlook is installed must be a member of the domain and the user must be a valid domain user.

This can also be done during the installation by setting the SERVICE_PRINCIPAL and USE_SSPI properties.

Antivirus configuration

To use the virus scanning feature you must first install antivirus software on the server.
The antivirus software must support commandline scanning.

1. Create virus scanner script

The Bluewhale clients create a zip file containing the attachments. The zip file is uploaded to the Bluewhale server.
When the antivirus field is checked Bluewhale Server will invoke the specified script with the uploaded file as argument.

The script must create two files:
<file name>.result
<file name>.log

When the script exits the two files are examined. If <file name>.result contains a single zero (0) the file is accepted. Otherwise, the file is rejected. It is common behaviour for antivirus scanners to return zero (0) if no virus is found. If <file name> is deleted it is also rejected, regardless of the contents of the <file name>.result file.

If the file is rejected the content of <file name>.log is shown to the user. Any messages to the user should be written to this file.

The following example uses McAfee for virus scanning.

Windows (runmcafee.bat - 3 lines) :

@echo off
"C:\Program Files\Network Associates\VirusScan\csscan.exe" /TARGET %CD%%1
echo %ERRORLEVEL% > %1.result

The following example uses Sophos (sav32cli) for virus scanning.

Windows (runSophosscan.bat - 3 lines) :

 @echo off
"C:\Program Files\Sophos\Sophos Anti-Virus\sav32cli.exe"
%1 -archive -ss -nc -vv -P=%1.log
echo %ERRORLEVEL% > %1.result

The following example uses ESET NOD32 for virus scanning.

Windows (runeset.bat - 3 lines) :

@echo off
"C:\Program Files\ESET\ESET NOD32 Antivirus\ecls.exe" %1
--base-dir="C:\Program Files\ESET\ESET NOD32 Antivirus"
--files --no-boots --arch --mail --sfx --rtp --pattern
--scan-timeout=300 --action=none --no-quarantine --log-rewrite --log-file=%1.log
echo %ERRORLEVEL% > %1.result

Test the script by running:

runavscan <file name>

Where file name is a zip file.
A harmless test virus can be obtained from

Verify the content of the <file name>.result and <file name>.log files.

2. Update Bluewhale Server settings

From the Bluewhale Server welcome page select "Administrator login". Choose Settings.

Check "Enable virus scan".
Enter the path to the virus scanner script, e.g.:

C:\Program Files\Bluewhale Server\runeset.bat

Optionally, you can specify a message to the recipient regarding the antivirus scan, e.g.:

The attached files have been scanned and found virus free.

Click "Save" to store the new settings.

Configure SSL

In order to encrypt all data sent using Bluewhale you must enable SSL.

1. Import or create certificate

From the Bluewhale Server welcome page select "Administrator login". Choose Settings > SSL.

If you already have a certificate just copy the key to the Key-field and click "Import key".
Then copy the certificate to the Certificate-field and click "Import certificate". Both the key and the certificate must be in PEM-format.

If you need to generate a new certificate click "Generate new key".
Then fill in your details and click "Generate CSR". You must now copy the CSR to your CA.

When you receive your certificate from the CA copy the certificate to the Certificate-field. If you have an intermediate certificate insert this in the same field but after your own certficate. Click "Import certificate".

For the new settings to take effect you must restart Bluewhale Server:

Go to Control panel > Adminstrative Tools > Services. Select "Bluewhale Server" and choose restart.

2. Update Bluewhale Server host URL

Choose Settings > General.

Update the host URL to use https, e.g.:

Remember to update the server URL in Bluewhale for Outlook clients and to open port 443 in your firewall.

If you are migrating from non-SSL to SSL you must remember to clear the Java application cache on the clients, otherwise they will continue to use non-SSL connections:

Go to Control panel > Java. In the "Temporary Internet files"-group select "View" and delete any "Bluewhale - Send" applications.

Two-factor download authentication

When two-factor download authentication is enabled, and the sender enters the mobile phone number of the recipient, the recipient is required to enter an SMS pincode in order to download the files.

In order to use this functionality you must have access to a compatible SMS gateway.
The gateway must accept HTTP GET requests of the following form:{countryCode}&n={phoneNumber}&m={message}

A compatible gateway is available from

To enable two-factor download authentication go the Bluewhale Server welcome page and select "Administrator login".
Choose "Settings" and then "Download pincode".

Check "Download pincode", enter the URL and parameters to your SMS gateway and click "Save".