6 WebShare WebObjects Server

The WebShare WebObjects 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 WebObjects 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 WebObjects 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 WebObjects Server, a high level of WebShare File Server security is ensured. The WebShare WebObjects 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 WebObjects 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 WebObjects Server which may run on a separate server machine. The WebShare WebObjects 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-ROM.

6.2 WebShare WebObjects Server files

6.2.1 "Contents/Resources/"

Each "*.wo" directory contains the "*.html", "*.wod" and "*.woo" files for the corresponding web page. They may be localized to the desired GUI (Graphical User Interface) language. 6.3 "Customization/Localization" describes how to localize/customize the WebShare GUI.

The script "sbin/start-websharewoa" starts the WebShare WebObjects 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:

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 WebObjects 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 WebObjects Server, first copy the "webshare.woa" package from "HELIOSDIR/var/run" to "HELIOSDIR/var/webshare".

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

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.
If customizations should also be valid in localized resources, then the "<language>.lproj" folders must also be customized.

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.3 "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, and French. Additional language localizations can only be done directly by HELIOS. Please contact your HELIOS partner for such requests.

6.4 HTTPS/SSL support

6.4.1 Introduction

This document 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.4 tools to accomplish this task.

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

Warning: 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 WebObjects Server it is required to configure the HTTPS/SSL port. A good port number is 443 (default for HTTPS). First, the WebShare WebObjects 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:

# cp var/run/webshare.woa/Contents/Resources/adaptorssl.sample var/conf/adaptorssl.key

Note: The preference SSLPort is described in 6.5 "Preference keys".

The WebShare WebObjects 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

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 (Sun Java 1.4 and newer)

The Sun JDK (version 1.4 and newer) ships with all security tools you need to configure SSL with the HELIOS WebShare WebObjects Server. The most important is the "keytool" located in the "JAVA_HOME/bin" directory of the Java runtime. Sun 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 WebObjects ships with a self-signed "dummy" certificate designed for initial evaluation testing.

Find more information about the "keytool" utility at:
http://java.sun.com/j2se/1.4.2/docs/tooldocs/tools.html

6.4.5 Creating a server certificate

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

2. Create a self-signed SSL server certificate for your server domain.

3. [Optional] Have a CA (Certification Authority) certify the SSL server certificate.

4. [Optional] Import the server certificate obtained from the CA into the keystore.

1. Decide on a server domain
The WebShare WebObjects 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 go to the command line on the WebShare WebObjects Server. "HELIOSDIR" must be replaced with the HELIOS installation directory, e.g. "/usr/local/helios" for the default installation:

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

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

What is the two-letter country code for this unit?
Example: DE (for "Germany" - check with your CA)

Answer 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>

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

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

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

6.4.6 Completion

6.4.7 Q & A

-----BEGIN NEW CERTIFICATE REQUEST-----
MIIBxzCCATACAQAwgYYxCzAJBgNVBAYTAkRFMRAwDgYDVQQIEwdHZXJtYW55MRAwDgYDVQQHEwdHYXJic2VuMR0wGwYDVQQKExRIRUxJT1MgU29mdHdhcmUgR21iSDEXMBUGA1UECxMOSEVMSU9TIFN1...
-----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)

Our experience is 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-----
MIIDRzCCAvGgAwIBAgIQX6oiydIYfaEABAZyXsUOlDANBgkqhkiG9w0BAQUFADCBqTEWMBQGA1UEChMNVmVyaVNpZ24sIEluYzFHMEUGA1UECxM+d3d3LnZlcmlzaWdu...
-----END CERTIFICATE-----

6.4.8 Known Issues

websharewoa: [2004-04-30 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.:

websharewoa: [2004-04-30 15:54:30 MEST] <main> com.webobjects.foundation.NSForwardException for com.webobjects.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 Sun JVM.

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

6.5 Preference keys

This section lists all the preference keys that are pertinent to the WebShare WebObjects 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 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.

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 WebObjects Server, see 8.1.11 "Switching WebShare to port 80 on the WebShare WebObjects Server" for configuration details.

Specifies the port number of the mDNS proxy server that is used for mDNS ("Bonjour") branding registrations. If more than one WebShare WebObjects 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 Base manual). If there should be the need to change a value, then make sure that both preference keys are assigned the same value!

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

Specifies the host name or IP address of the WebShare WebObjects Server. This is useful on machines with multiple IP addresses/host names. If this preference is not set, the WebShare WebObjects Server can be reached via any IP address/host name on the machine. See also WOPort above.

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

List of WebShare File Server host names or IP addresses which are allowed to be used on the WebShare WebObjects 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.

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

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

This preference allows specifying a password for a protected HTML page, which allows monitoring the WebShare WebObjects 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 WebObjects Server and WebObjects work internally.

The default time-out value for uploads and downloads of the WebShare WebObjects 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.

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

Modern browsers, e.g. Safari, Firefox, Internet Explorer support "gzip" compressed HTML pages. If supported by the browser, the WebShare WebObjects 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-5x, depending on the content. In case of problems with compressed pages this feature can be turned off by setting this preference to FALSE.

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

If this preference is set to TRUE, and the client is an Apple iPhone, a link becomes available for each displayed image on the preview page, which displays the extended image information. In default mode (FALSE) clicking the image is still required.

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.

Name	Function
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
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


WebShare UB⁺ User manual

WebShare UB+ User manual