6 WebShare Web Server

The WebShare Web Server (“webshare.woa”) is a Java program running on a server with an internet connection. It can be installed on the same machine where the WebShare File Server is installed, in which case it is called a “single server solution”. To increase the level of file system security, the WebShare Web Server should be installed on a separate server, in a “two-tier server solution”.

Ideally no other applications or services would be running on the WebShare Web Server. This allows the blocking of all ports and services (by software and/or hardware firewalls), except for those required by WebShare.

Due to the fact that no data files are stored or cached on the WebShare Web Server, a high level of WebShare File Server security is ensured. The WebShare Web Server uses one dedicated TCP/IP port for all web clients, by default 2009.

During the installation of HELIOS WebShare the packed file “websharewoa.tar” is installed in the directory “HELIOSDIR/etc/webshare”. The “start-helios” command then extracts the file in the directory “HELIOSDIR/var/run” to the “webshare.woa” package.

6.1 WebShare license information

The WebShare product includes two server components. The WebShare File Server which is licensed on a given HELIOS machine ID (mach ID) and a WebShare Web Server which may run on a separate server machine. The WebShare Web Server belongs to the WebShare server product and will not require a separate WebShare activation key.

The complete HELIOS software license terms must be accepted during the installation and can be found on the product CD.

6.2 WebShare Web Server files

The “HELIOSDIR/var/run/webshare.woa/Contents/Resources/” folder contains the following files:

6.2.1 “Contents/Resources/”

Accounting.wo/: Accounting HTML page component
AccountingDetails.wo/: HTML page component for detailed accounting information
AdmPrefs.wo/: Preferences administration HTML page component
AdmShares.wo/: Sharepoint administration HTML page component
AdmUsers.wo/: User administration HTML page component
Admin.wo/: Main administration HTML page component
FileBrowser.wo/: HTML component for browsing files and directories
FilePreview.wo/: HTML component for document and image previews
ForgotPassword.wo/: Template HTML component for forgotten passwords
Goodbye.wo/: Logout HTML page component
Login.wo/: Login HTML page component
Main.wo/: Welcome and select server page component
PagePreview.wo/: HTML component for image proofs
RegisterNewUser.wo/: Template HTML component for registering new users
Sharepoints.wo/: Sharepoint listing HTML page component
Upload.wo/: HTML component for uploading files
UserPrefs.wo/: User preferences HTML page component
WSBrandingEditor.wo/: HTML Branding Editor component
WSCSSComponent.wo/: System internal component
WSExceptionPage.wo/: System internal component
WSFileAnnotationsContent.wo/: System internal component
WSFileAnnotationsEntryContent.wo/: System internal component
WSFileAnnotationsTemplate.wo/: Template for annotations dialog
WSFileListingMenu.wo/: System internal component
WSOpenFile.wo/: Template for open file page
WSToolbar.wo/: HTML toolbar component
WSToolbarButton.wo/: System internal component
WSToolbarLink.wo/: System internal component
WSUploadForm.wo/: System internal component
WSUploadReport.wo/: System internal component
WSUploadStatus.wo/: System internal component
WebShareStats.wo/: Server statistics HTML page component
ZipDownload.wo/: System internal component

Each “*.wo” directory contains the “*.html”, “*.wod” and “*.woo” files for the corresponding web page.

The script “sbin/start-websharewoa” starts the WebShare Web Server daemon. Usually, it is started by the “srvutil start websharewoa” command during “start-helios”. In case of startup problems, it can be started manually to monitor the error messages in a terminal window via:

# cd /usr/local/helios 
# sbin/start-websharewoa

Additional logging is reported to the WebObjects log files. They are located in “HELIOSDIR/var/adm/” and are called “websharewoa.log”, with the appendices “.0” (yesterday), to “.6” (seven days ago). All internal WebObjects messages are reported to “websharewoa.log”. All HELIOS generated WebShare Web Server messages are reported to the system messages file.

6.3 Customization/Localization

WebShare includes user selectable localized language support for menus, messages, administration, dialog boxes, etc. This chapter describes how to customize an existing language version.

Note:: This section is about customizing the “webshare.woa” package. If no customizing is done, then this section can be ignored.

: To customize the WebShare Web Server, first copy the “webshare.woa” package from “HELIOSDIR/var/run” to “HELIOSDIR/var/webshare”.

All customization must be done in “var/webshare”. This is because whenever WebShare is started it looks for “webshare.woa” in “var/webshare”. Only if it cannot be retrieved from there, is it taken from “var/run”. The idea is that “webshare.woa” is always replaced in “var/run” in case of software updates. Being in “var/webshare”, localizations and other adjustments are preserved.

Note:: However, for new WebShare product versions or updates that incorporate new features, you must copy the “webshare.woa” package anew from “var/run” to “var/webshare”, overwriting the older package, and apply the customization/localization again. Otherwise it might be incompatible with the used WebShare File Server or new features might not be available.

Note:: Mac OS X:
Use the Show Package Contents option to display the contents of the “webshare.woa” package, and subsequently of the “.wo” files in the “Contents” > “Resources” folder, to make the “.wod” and “.html” files visible.

6.3.1 Customizing “*.html” files

Customize all “*.html” files, using UTF-8 characters. The WebObjects Builder application can do this by showing the correct layout. You may also use any other HTML tool. Before changes in “*.html” files become valid, the “websharewoa” service must be stopped and restarted.

6.3.2 Customizing “*.wod” files

Customize all “*.wod” files, using UTF-8 strings. You may customize the strings with any UTF-8 compatible text editor. Before changes in “*.wod” files become valid, the “websharewoa” service must be stopped and restarted.

6.3.3 Customizing action scripts

Custom action scripts are customized by putting #Title=UTFname into the script within the first 5 lines.

Likewise, the #NameField= comment in any script can be edited. The next time you log in and select a script from the WebShare “Actions” toolbar item, a field becomes available, allowing you to submit values to the script.

Refer to 7.4 “WebShare scripts” for details on creating or customizing WebShare custom scripts and action scripts.

6.3.4 Adding additional language localizations

WebShare includes support for English, German, Japanese, Spanish, and French. Additional language localizations can only be done directly by HELIOS. Please contact your HELIOS partner for such requests.

Note:: If customizations should also be valid in localized resources, then the “<language>.lproj” folders must also be customized.

6.4 HTTP/SSL support

6.4.1 Introduction

This section outlines how to configure your SSL setup. HELIOS WebShare SSL support is built using the standard Java security SSL implementation. In this document, we will describe how to use the standard JDK 1.5 tools to accomplish this task.

What does SSL mean?

SSL (Secure Sockets Layer) is a protocol designed by Netscape Communications Corporation to provide encrypted communications on the internet. SSL is layered beneath application protocols such as HTTP, SMTP, FTP, Telnet, Gopher, and NNTP and above the connection protocol TCP/IP. It is used by the HTTPS access method. SSL works by using a secret key to encrypt data that is transferred over the SSL connection. Many modern browsers support SSL, and many websites use the protocol to obtain confidential user information, such as credit card numbers. By convention, URLs that require an SSL connection start with https: instead of http:.

6.4.2 Background

An SSL-enabled server usually uses a secured file or database called keystore to store the keys and certificates for the server. These security credentials are used to prove to clients that the server is legitimately operating on behalf of a particular domain. If your server will only need to act as one domain, you only need one key entry and certificate in the keystore. Keys are stored in the keystore under aliases. Each alias corresponds to a domain name, e.g.:
webshare.yourserver.com.

Certificates attempt to guarantee that a particular party is who they claim to be. Certificates are trusted based on who signed the certificate. If you only require light security, e.g. for internal use on trusted networks, etc. you can use “self-signed” certificates. Self-signed certificates encrypt the communication channel between client and server. However the client must verify the legitimacy of the self-signed certificate through some other channel. The most common client reaction to a self-signed certificate is to ask the user whether to trust the certificate or to silently trust that the certificate is legitimate. Unfortunately, blindly accepting self-signed certificates opens up the system to “man-in-the-middle” attacks.

The advantage of a self-signed certificate is that you can create them for free or for testing and evaluation. In addition, you can safely use a self-signed certificate if you can verify that the certificate you are using is legitimate. So if a system administrator creates a self-signed certificate, then personally installs it on a client’s truststore (so that the certificate is trusted) you can be assured that the SSL connection will only work between the client and the correct server.

For higher security deployments, you should get your certificate signed by a CA (Certificate Authority). Clients truststores will usually contain certificates of the major CAs and can verify that a CA has signed a certificate. This chain of trust allows clients to trust certificates from servers they have never interacted with before. Certificate signing is similar to a public notary (with equivalent amounts of verification of identity, record keeping, and costs).

6.4.3 Quick setup with the built-in “default” certificate

HELIOS WebShare ships with a self-signed “default” certificate designed for initial evaluation testing.

Important:: The following instructions are for demo purposes only. Do not use the example key file (“adaptorssl.key”) that is shipped with the software to secure your WebShare server since the key is available for everyone!
We strongly recommend to create your personal server certificate (see 6.4.5 “Creating a server certificate”)!

On the WebShare Web Server it is required to configure the HTTPS/SSL port. A good port number is 443 (default for HTTPS). First, the WebShare Web Server must be stopped and then started again to ensure that the latest version gets unpacked in “var/run/webshare.woa”. The quick setup commands are:

# cd /usr/local/helios 
# bin/srvutil stop websharewoa 
# bin/srvutil start websharewoa 
# bin/prefvalue -k Programs/websharewoa/SSLPort -t int 443 
# cp var/run/webshare.woa/Contents/Resources/adaptorssl.sample
  var/conf/adaptorssl.key 
# echo hellothere > var/conf/adaptorssl.pass

Note:: The preference SSLPort is described in 6.5 “Preferences”.

: Restart the WebShare Web Server via:

# bin/srvutil stop websharewoa
# bin/srvutil start websharewoa

The WebShare Web Server will now be available via standard HTTP as well as HTTPS. The HTTPS connections can be started via the following browser URL: https://webshare.yourdomain.com

The DNS name must be replaced with the correct name for your WebShare Server.

Note:: If the default port for SSL is not 443 the URL must include the port number, e.g. for port 2009 the browser URL is:
https://webshare.yourdomain.com:2009

6.4.4 Security tools (Oracle Java 1.5 and newer)

The Oracle JDK (version 1.5 and newer) ships with all security tools you need to configure SSL with the HELIOS WebShare Web Server. The most important is the “keytool” located in the “JAVA_HOME/bin” directory of the Java runtime. Oracle JVMs preserve keystores and truststores on the file system as encrypted files. The “keytool” is used to create, read, update, and delete entries in these files. HELIOS WebShare ships with a self-signed “dummy” certificate designed for initial evaluation testing.

Find more information about the “keytool” utility at:
docs.oracle.com/javase/1.5.0/docs/tooldocs/

6.4.5 Creating a server certificate

In order to configure SSL on your server you need to complete the following tasks:

Decide on your HELIOS WebShare server’s domain.
Create a self-signed SSL server certificate for your server domain.
(Optional) Have a CA (Certification Authority) certify the SSL server certificate.
a) Generate a CSR (Certificate Signing Request).
b) Submit your CSR to a CA for signing.
(Optional) Import the server certificate obtained from the CA into the keystore.

Detailed instructions for each of the above steps:

1. Decide on a server domain
The WebShare Web Server domain should match the server host name, e.g. “webshare.yourdomain.com”.

2. Create a self-signed server certificate
In order to create a self-signed server certificate, use the “keytool” utility on the WebShare Web Server:

# cd usr/local/helios/var/conf

Generate a key using the Java “keytool”, which is located in the Java “/bin” directory.

# keytool -genkey -keystore adaptorssl.key -keyalg 
  rsa -alias webshare.yourdomain.com

Please complete the following questions:

Enter the keystore password: <Your private password>

What is your first and last name? webshare.yourdomain.com (This must match your server DNS name)

What is the name of your organizational unit? <Your organizational unit>

What is the name of your organization? <Your Company Name>

What is the name of your City or Locality? <Your City or Locality>

What is the name of your State or Province? <Your State or Province or Country>

What is the two-letter country code for this unit?

Example:: DE (for “Germany” – check with your CA)

Confirm that the settings are correct or abort via “Ctrl-C” and start over again.

Enter key password for <webshare.yourdomain.com> <Press ENTER key only; not supported by WebShare>

The “adaptorssl.key” file is now being created.

: As a next step enter the keystore password in the configuration file “adaptorssl.pass”, which will be used by the WebShare Web Server, to allow access to the “adaptorssl.key” content.

Create the “adaptorssl.pass” password file via:

# cd /usr/local/helios/var/conf
# echo "yourpassword" > adaptorssl.pass

To secure your keystore password, the file permissions of “adaptorssl.pass” can be changed so that no user can access this file, only the root user could have access, e.g.:

# chmod 600 adaptorssl.pass

If you do not plan a CA signed certificate the self made HTTPS certificates should work and the additional steps are not required.

3. Obtain a CA signed certificate
If you decide to get a CA signed certificate, you must first export the certificate in the standard CSR format. You can do this using the Java “keytool”:

# keytool -certreq -keystore adaptorssl.key -alias 
  webshare.yourdomain.com -file <CSR_filename>

: Substitute “webshare.yourdomain.com” with your full server name and specify a file name for CSR you wish to produce. Submit the generated CSR to the CA and follow their instructions to get it signed.

4. Import server certificates
If you had a CA sign your server certificate you must import it into your existing keystore using the Java “keytool”:

# keytool -import -keystore adaptorssl.key -trustcacerts 
  -alias webshare.yourdomain.com -file signed_certificate_file

It is important that the key has the same associated alias than that used when creating the CSR. Otherwise you will receive an error.

Additionally you have to install the root certificate and – depending on the CA and certificate type – one or more intermediate certificates. Consult the CA's documentation or support for details.

Example for CA root certificate:

# keytool -import -keystore adaptorssl.key -trustcacerts
  -alias root -file root_certificate_file

Example for CA intermediate certificate:

# keytool -import -keystore adaptorssl.key -trustcacerts
  -alias intermediate -file intermediate_certificate_file

The aliases “root” and “intermediate” are for keystore internal organisation only and can be renamed according to your needs.

It is important that the keystore contains the complete certificate chain, from your domain certificate up to the CA root certificate. Otherwise, the “websharewoa” service will not start up properly with HTTPS.

6.4.6 Completion

: Restart of the WebShare Web Server.

# srvutil stop websharewoa 
# srvutil start websharewoa

SSL setup is now complete and WebShare can be reached via both HTTP and HTTPS.

Note:: To allow only HTTPS access and NOT HTTP, you must set the WOPort preference to 0 (see 6.5 “Preferences”).

6.4.7 Q & A

How will a “Certificate Request” look like?

-----BEGIN NEW CERTIFICATE REQUEST----- 
MIIBxzCCATACAQAwgYYxCzAJBgNVBAYTAkRFMRAwDgYDVQQIEwdHZXJt 
YW55MRAwDgYDVQQHEwdHYXJic2VuMR0wGwYDVQQKExRIRUxJT1MgU29m 
dHdhcmUgR21iSDEXMBUGA1UECxMOSEVMSU9TIFN1... 
-----END NEW CERTIFICATE REQUEST-----

Usually this needs to be submitted including the “-----BEGIN...” and “-----END...” lines into your CA (Certificate Authority, e.g. verisign.com)

Why is my browser telling me that the certificate does not match?

There can be several reasons for this:

Your server domain name URL does not match the certificate
Your certificate has not been signed by a CA
You certificate has expired
Your browser does not know about your CA, e.g. VeriSign is installed in all major browsers

Our experience shows that Mozilla based browsers provide more detailed information on certificates than others. In a case of a problem these browsers can be used to show how the CA certificate response will look like.

-----BEGIN CERTIFICATE----- 
MIIDRzCCAvGgAwIBAgIQX6oiydIYfaEABAZyXsUOlDANBgkqhkiG9w0B 
AQUFADCBqTEWMBQGA1UEChMNVmVyaVNpZ24sIEluYzFHMEUGA1UECxM+ 
d3d3LnZlcmlzaWdu... 
-----END CERTIFICATE-----

6.4.8 Known issues

Problem:

If “websharewoa” issues an error message during startup:

websharewoa: [2009-11-28 15:54:30 MEST] <main> Unable to 
establish an SSL connection to port 443 on this host

and then exits, make sure that the SSL port is not used by another application, e.g.:

# netstat -an | grep 443

should not list a line like below:

*.443 *.* 0 0 24576 0 LISTEN

Also check for the following message:

websharewoa: [2009-11-28 15:54:30 MEST] <main> com.webob- 
jects.foundation.NSForwardException for com.webob- 
jects.foundation.NSForwardException for 
java.security.NoSuchAlgorithmException: Algorithm 
SunX509 not available "Algorithm SunX509 not available"

indicates that the used JVM implementation does not offer SSL support. Check for an update to that JVM or install the Oracle JVM.

Problem:: The Microsoft Internet Explorer 6 cannot use a port other than 443 (default) for a “websharewoa” secure HTTPS connection.

6.5 Preferences

This section lists all the preference keys that are pertinent to the WebShare Web Server. Find a description of how to set, view, change or delete preferences, with the HELIOS “prefdump”, “prefvalue”, and “prefrestore” utility programs in “HELIOS utility programs” in the HELIOS Base manual.

Important:: Make sure that preference keys DO NOT start or end with a slash (“/”) character, and note that they are case-sensitive! Also, if any preference key or preference value includes spaces, that key or value must be enclosed in quotes.

The following keys require a restart (see “srvutil” in the HELIOS Base manual) of the service to take effect:

: Key: Programs/websharewoa/<preference>

WOPort

int

2009

Specifies the WebShare Web Server port number for HTTP access. If set to “0” (without quotes) any HTTP connection to the WebShare Web Server is denied, only HTTPS/SSL connections are accepted. In that case, make sure the preference SSLPort is set, otherwise no connection to the WebShare Web Server can be established.

Note:: In the event that hat you wish to use HTTP port 80, and Apache or another web server is also running on the WebShare Web Server, see 9.1.11 “Switching WebShare to port 80 on the WebShare Web Server” for configuration details.

MDNSPort

int

2006

Specifies the port number of the mDNS proxy server that is used for mDNS (“Bonjour”) branding registrations. If more than one WebShare Web Server is used, all used ports must have the same number.

Important:: The value of this preference needs to be identical with the mDNS proxy server TelnetPort preference (see HELIOS Base manual). If there should be the need to change a value, then make sure that both preference keys are assigned the same value!

SSLPort

int

443

Specifies the WebShare Web Server port number for HTTPS/SSL connections to the browser.

WOHost

str

(see description)

Specifies the host name or IP address of the WebShare Web Server. This is useful on machines with multiple IP addresses/host names. If this preference is not set, the WebShare Web Server can be reached via any IP address/host name on the machine. The preference can also be set to a comma-separated list of IP addresses/host names. In addition, this preference allows specifying a port or SSL port, meaning that, if a port or SSL port is specified, the default settings (given by WOPort and SSLPort) are overridden.

Example 1:

(myDomain:2035:2036; WOPort=2009; SSLPort=443;)

For “myDomain”, the default settings 2009 and 443 are overridden.

Access to the application:
http://myDomain:2035
and via SSL:
https://myDomain:2036

Example 2:

(myDomain::2036; WOPort=2009; SSLPort=443;)

For “myDomain”, no individual port is specified so the standard settings apply.

Access to the application:
http://myDomain:2035
and via SSL:
https://myDomain:2009

Example 3:

(myDomain:0:2036; WOPort=2009; SSLPort=443;)

Specifying the port “0” for “myDomain” means that there are no standard (i.e. unencrypted and therefore insecure) connections available.

Access via SSL only:
https://myDomain:2036

WSHostName

str

localhost,*

Specifies the WebShare File Server default host name prompt for the login dialog. It corresponds to the WebShare File Server entry in the WebShare login page. This preference can also be set to a comma-separated list of IP addresses or host names. In this case a pop-up menu to choose a WebShare File Server will be available at the login dialog.

Also aliases for IP addresses/host names can be defined:

prefvalue -k 'Programs/websharewoa/WSHostName' -t str 
"localhost,Server 1=fileserver,Server 2=172.16.2.222"

In this case, a pop-up menu will be available to choose a WebShare File Server showing the strings “localhost”, “Server 1”, and “Server 2”.

It is also possible to specify a port number with the host name, e.g.

prefvalue -k 'Programs/websharewoa/WSHostName' -t str
"localhost:2010,Server 1=fileserver,Server 2=172.16.2.222"

However, specifying a port number requires that this port has also been set, together with the host name, in the WSAllowedHostNames preference, provided that WSAllowedHostNames was specified at all. If not, the connection is refused and an error message is issued.

If an “*” is found as a host name in the WSHostName preference the user is allowed to enter a file server name manually, in addition to choosing a file server from the pop-up menu:

prefvalue -k Programs/websharewoa/WSHostName -t str
"localhost:2010,Server 1=fileserver,Server 2=172.16.2.222,*"

However, if more than one host name or/and host alias are defined together with an “*”, JavaScript needs to be activated in the client application to get a pop-up menu displayed – otherwise a plain text field, showing the first defined hostname, is displayed.

If only one host name or alias is defined, the user can neither choose nor enter a file server name.

The following examples give an overview of the possible cases:

Preference value: "*"
Display on login page: an empty text field.

Preference value: "localhost:2010"
Display on login page: the string "localhost:2010".

Preference value: "Server 1=localhost"
Display on login page: the string “Server 1”.

Preference value: "localhost,*" (default)
Display on login page: a text field with the value “localhost”.

Preference value: "Server 1=localhost,*"
Display on login page: a text field with the value “Server 1”.

Preference value: "Server 1=localhost,otherhost"
Display on login page: a pop-up menu with the values “Server 1” and “otherhost”.

Preference value: "Server 1=localhost,otherhost,*"
Display on login page: a pop-up menu with the values “Server 1” and “otherhost”, and in addition the ability to enter a file server name manually.

Note:: If a list of file servers without an “*” is defined in the “WSHostName” preference, only file server names or file server aliases defined in this preference are accepted. However, if only one file server name or alias is defined – or an “*” is found as a host name – the file server name defined by the “wshost” parameter (see wshost) is used.

WSAllowedHostNames

str

(see description)

List of WebShare File Server host names or IP addresses which are allowed to be used on the WebShare Web Server. The string must be comma-separated if more than one “allowed” host name or IP address is specified. If not set, all host names are allowed.

WSHostPort

int

2010

Specifies the WebShare File Server port number. If more than one WebShare File Server is used, they all have to use the same port.

Note:: The value of this preference needs to be identical with the WebShare File Server preference TcpPort (7.5 “Preferences”). If there should be the need to change a value, then make sure that both preference keys are assigned the same value!

WSEventDisplayPassword

str

This preference allows specifying a password for a protected HTML page, which allows monitoring the WebShare Web Server and the events it is processing. By default, the page is unavailable until a password is set. For security reasons, this preference should not be used unless you are an WebObjects deployment specialist and you know how the WebShare Web Server and WebObjects work internally.

WSUploadTimeOut

int

86400

The default time-out value for uploads and downloads of the WebShare Web Server is 24 h (=86400 s). If more time is needed, e.g. due to a slow internet connection, this preference may be set to a higher value.

WOSessionTimeOut

int

3600

Specifies that, after a user has been idle for a time, i.e. no web activity has occurred, the session will automatically be closed after one hour (=3600 s).

WSGZIPResponse

bool

TRUE

Modern browsers, e.g. Safari, Firefox, Internet Explorer support “gzip” compressed HTML pages. If supported by the browser, the WebShare Web Server generates “gzip” compressed HTML pages. For slow connections, e.g. via modem or ISDN lines this will increase the browsing performance by a factor of 2-5, depending on the content. In case of problems with compressed pages this feature can be turned off by setting this preference to FALSE.

WSPrintJavaExceptions

bool

FALSE

If this preference is set to TRUE, and an error occurs, a stack trace (debugging information) is printed on the error page.

JavaOptions

strlist

The values of this preference are passed through to the Java command when starting the “websharewoa” service. If specified, behavior, performance or debugging options can be set.

Note:: Use this preference with caution! Providing invalid arguments will preclude “websharewoa” from starting! Providing wrong argument values can cause considerable performance issues.

6.5.1 WOStarter preference keys

WatchdogInterval: int
600; Specifies the interval in seconds in which the watchdog process checks the WebShare Web Server (“websharewoa”) for plausibility of its output to the web browser.
ResponsePositive: strlist
""; Specifies a list of strings that are mandatory in the WebShare Web Server response to the web browser if the behavior is normal. If just one of these strings is missing, the “websharewoa” service is restarted. An example for a mandatory string is: “<!DOCTYPE html PUBLIC”.
ResponseNegative: strlist
""; Specifies a list of strings that must not be contained in the WebShare Web Server response to the web browser. If just one of these strings is included, the “websharewoa” service is restarted.

HELIOS Manuals November 22, 2013