IcedTea-Web

From IcedTea

The IcedTea-Web project provides a Free Software web browser plugin running applets written in the Java programming language and an implementation of Java Web Start, originally based on the NetX project.

1 Getting IcedTea-Web

You can get the IcedTea-Web source in several different ways.

Grab the source tarballs:

wget http://icedtea.wildebeest.org/download/source/icedtea-web-1.6.2.tar.gz

Anonymous clone using mercurial:

hg clone http://icedtea.classpath.org/hg/release/icedtea-web-1.6

Or try the bleeding edge:

hg clone http://icedtea.classpath.org/hg/icedtea-web

2 Building IcedTea-Web

You should have gtk2-devel and xulrunner-devel (mozilla-plugin) packages installed. Then build as follows. $ indicates that a command should be executed as a normal user, # indicates that commands that should be executed as root:

$ ./autogen.sh # skip this if you are using a release tarball
$ ./configure
$ make
# make install

This will install IcedTea-Web into /usr/local/. You can use the --with-jdk-home argument to configure to specify the JDK that IcedTea-Web should build and run against. IcedTea-Web has only been tested with JDKs built using IcedTea. Please see the README file for more details.

3 Testing IcedTea-Web

NOTE as of March 26, 2013, the default setting in IcedTea-Web is to not run unsigned applets automatically.

For test suite purposes, you should use itweb-settings to bring the security level to 'low' for these applets to run.

Build as follows:

./autogen.sh
./configure --prefix=<Location to destination where testing installation will be saved eg.: /home/user/icedtea-web-image> (--disable-docs will increase speed of your testing quite a lot)
make
make check
make run-cpp-unit-tests 
make install
make run-netx-dist-tests

make check will run various unit tests. For unit-tests please try to put all your debugging outputs to stderr and so try to keep stdout as clear as possible. Results are stored under tests.build/index_unit.html and tests.build/netx/unit/{stderr.log,stdout.log,tests-output.xml}. As of 2014-04-08, Icedtea-Web does not pass all tests. For details see Reproducer Failures.

make run-netx-dist-tests will run system-level tests using the installed IcedTea-Web, so this step requires a make install. Results are stored under tests.build/index_reproducers.html and tests.build/netx/jnlp_testsengine/{stderr.log,stdout.log,tests-output.xml}.

Warning - before running reproducers, be sure that some other netx.jar is not already on your classpath. This happens almost always when you have installed icedtea6 < 1.10 or IcedTea-Web 1.0.X. You can test that by running java net.sourceforge.jnlp.runtime.Boot. You should see some sort of ClassNotFoundException if netx.jar is not already on your classpath. If you have icedtea6 < 1.10 installed, remove (renaming is not enough) netx.jar from your icedtea6 installation (you can always replace it later with your own or by reinstalling icedtea6). If you have IcedTea-Web 1.0.X installed, uninstall IcedTea-Web. If you do not remove this netx.jar, then you will be testing this installed jar instead of your built one. You are also likely to get lots of spurious failures as a result of trying to access classes across jars.

3.1 Whitelisting

When running reproducers using make run-netx-dist-tests you can choose which tests to run using the whitelist $ICEDTEA)WEB_HOME/netx-dist-tests-whitelist.

The configure offers two options when using the whitelist:

./configure : process all reproducers, run with whitelist on test-case name of processed reproducers

./configure --enable-whitelist-processing : process with whitelist on directory name of reproducers, run all processed reproducers.

Using --enable-whitelist-processing is useful if for example, you want to run a small subset of reproducers, but you do not want to compile every single reproducer that Icedtea-Web has (which can take some time).

3.2 New Reproducers

If you are writing a new reproducer, follow Reproducers for more information.

3.3 Test Failures

The test system can be sensitive to certain conditions, especially for browser tests. See Reproducer Failures for details.

3.4 Cpp tests

Since 1.4, run as make run-cpp-unit-tests

3.5 Test Cases

Before every release, we like to run through all the tests cases that we have collected to check for regressions. Please note especially live-connect tests [1]

3.6 Logging

Logging inside IcedTea-Web tests (both unit and reproducers) is handled by ServerAccess' static methods logNoReprint, logOutputReprint, logErrorReprint and logException (subject to changes from possible refactoring). Everything logged by these methods is sorted into an XML file shared by all tests which have invoked these methods. The default XML file is ServerAccess-logs.xml inside working directory. Other than XML, plaintext files are also kept as stderr.log, stdout.log and the combined all.log. These files record id of class and method (and browser) as XML do.

When testsuite is launched from commandline Makefile, an HTML file is also generated from the XML. This HTML serves as fully capable navigated log file easily accessible (directly to test method) from test results. When using this file online, be patient as it may be several megabytes in size.

When testsuite is run from IDE, you are recommended to switch ServeAccess.LOGS_REPRINT to true, which will cause logs reprinted to IDEs stdout/err gatherers.

Please note, when writing reproducer's source code, do not use logging. Use System.out/err as usual. During compilation and runtime individual reproducers (unlike testcases) do not have access to ServerAccess class.

4 Usage

4.1 End Users

4.1.1 Netx

Once the javaws binary is built and installed, it can be used by

javaws somefile.jnlp

Please see the man page (man javaws), the about dialog (javaws -about) and the help message (javaws -help) for more information.

4.1.2 Plugin

The plugin can be used in Firefox, Chrome and Chromium, and Midori (and possibly others) by creating a symlink to it under the Mozilla plugins directory:

cd ~/.mozilla/plugins && ln -s $PREFIX/lib/IcedTeaPlugin.so libjavaplugin.so

Where $PREFIX is the prefix of the IcedTea-Web installation (/usr/local by default). As far as we know, there is no such single-user possibility for Opera.

If you want to install the plugin for all users to be used in Firefox, Chrome and Chromium, and Midori (and possibly others), you must create a symlink to it under the global Mozilla plugins directory:

cd /usr/lib{64}/mozilla/plugins/ && ln -s $PREFIX/lib/IcedTeaPlugin.so libjavaplugin.so

for Opera you must use its own directory:

cd /usr/lib{64}/opera/plugins && ln -s $PREFIX/lib/IcedTeaPlugin.so libjavaplugin.so

For both all-users options you must be root.

Restarting the browser should cause the plugin to be picked up by browsers. Browsers that are known to work include Firefox, Chrome and Chromium, Opera, and Midori. Other browsers supporting the NPAPI should work just as well.

For older versions of IcedTea-Web (< 1.1), $PREFIX needs to be the the path to the JDK itself: /path/to/icedtea/jdk/jre/lib/

4.2 Applet/Web Start Developers

IcedTea-Web 1.1 and later provide all the necessary netscape.javascript.* and javax.jnlp.* classes that applets and web start applications use. However, unlike IcedTea-Web < 1.1 (or older releases of icedtea6) the jars that provide these classes will not be automatically be picked up by the JDK.

• netscape.javascript.* classes are included in plugin.jar.
• javax.jnlp.* classes are included in netx.jar.

Please add these JARs to your classpath when building.

4.2.1 Splash-screen

Since September 2012 the splash-screen is available for both plugin and javaws. You can customize it via two environment variables: ICEDTEA_WEB_PLUGIN_SPLASH and ICEDTEA_WEB_SPLASH. Currently it can have only one of the following values: default for using default splashscreen, or none to disable it. If these variables are not set or are empty, default is used.

4.3 Packagers

IcedTea-Web 1.1 (and later) can be installed into a regular prefix (/usr/ or /usr/local/ or anything else). Unlike IcedTea-Web 1.0, you do not need to install IcedTea-Web into a JDK or JRE directory. IcedTea-Web uses a JDK to build itself (specified using --with-jdk-home). IcedTea-Web will use the JDK it was compiled against to run. The launchers (javaws and itweb-settings) are now shell scripts and can be customized if needed.

5 Configuration

A number of options in IcedTea-Web can be configured by using the Control Panel.

IcedTea-Web also supports using a deployment.properties file located at ~/.icedtea/ (for 1.4 and earlier) or ~/.config/icedtea-web/ (for 1.5 and later). Please see Java Deployment Configuration for more details.

6 Filing bugs

If you encounter any issues when using either the plug-in or Web Start implementation (javaws), please file a bug on the IcedTea Bugzilla. If possible, logs should be attached to the bug as they are immensely helpful.

To get the logs for the plug-in: Close firefox and restart it from command-line as 'ICEDTEAPLUGIN_DEBUG=true firefox 2>&1 | tee plugin.log' and re-create the bug. Once done, close Firefox. The logs that need to be attached to the bug are the plugin.log file created by the command, and all files in ~/.icedtea/log/ or ~/.config/icedtea-web/log/ (~/.icedtea/java.std* files in older versions).

To get the logs for the Web Start implementation (javaws): Launch javaws from the terminal as 'javaws -verbose [problem JNLP file] 2>&1 | tee javaws.log'. The log that needs to be attached is the javaws.log file created by the command.

Since 1.4 most of the errors are graphically presented to the user and stack-trace leading to error and many other interesting information can be shown on demand. This bug report is just one click away from "error screen" and can be most useful for us!

6.1 offline debugging of your app

Since 1.5.1, itw have extended support for offline run. If your application is not working, and you cannot allow us to connect to it, you may:

• run javaws -Xclearcache
• javaws/browser+applet run your app
• and send us the context of your $XDG_CACHE_DIR/icedtea-web directory.
  • in case of applet also the reposnible html page, as it is not cached by ITW
• thanks to this, we can run this app offline (for javaws with help of -Xoffline, for applet by simply being offline) and fix all but network issues.

7 Common Issues

7.1 IcedTea-Web is not localized

Yes, IcedTea-Web is missing a large number of translations. Patches are welcome! The English translations are available as a Messages.properties file and should be the most up to date of all translations. Please translate it into your language (or update an existing translation) and post it to the mailing list or file a bug in the IcedTea Bugzilla.

Since 1.4 there exists translations to CZ, DE, and PL languages. Thanks to the community for these translations!

7.2 Invalid XML

An error like:

netx: Unexpected net.sourceforge.jnlp.ParseException: Invalid XML document syntax. at net.sourceforge.jnlp.Parser.getRootNode(Parser.java:1203)

indicates that the JNLP file is not valid XML. The error happens because netx uses an XML parser to parse the JNLP file. Other JNLP client implementations may use more lenient parsers and may or may not work with the given JNLP file. Errors caused by malformed JNLP files can often lead to subtle bugs, so it is probably best to fix the JNLP file itself. A tool like xmlproc_parse might be able to pinpoint the error.

7.3 Invalid spec version

 netx: Unexpected net.sourceforge.jnlp.ParseException: Spec version not supported (supports 1.0 1.5 6.0) at net.sourceforge.jnlp.Parser.<init>(Parser.java:137)

As far as we know, there are only a few spec versions for JNLP files: 1.0, 1.5 and 6.0 (and the point releases for 6.0). However, a number of JNLP files use unspecified spec numbers. Netx should be able to handle most of them with the latest release, but if you run into this exception, please send an email to the mailing list with a link to the JNLP file causing this exception.

7.4 Netx hangs while downloading an application

There are known deadlocks in downloading code. They don't happen too frequently, but if netx appears to hang while downloading an application, try killing the javaws process and starting it again. If the problem is reproducible, please file a bug at the IcedTea Bugzilla.

7.5 Plugin hangs Firefox

It is possible for the plugin to hang Firefox because it is run in the same process. A workaround is to navigate to 'about:config' in Firefox and change dom.ipc.plugins.java.enabled to 'true'. This should not have any ill effects.

Bug reports for these cases are still appreciated; for developers please see Fixing IcedTea-Web Browser Hanging.

8 Code style

IcedTea Web's code style is intended to be as close to that of OpenJDK as possible. Since the default Eclipse styling is very similar as well, we use a slightly tweaked Eclipse default style for IcedTea Web. The style settings files are available in the IcedTea Web repository

The main points are:

• Only spaces are used, no tabs at all.
• Default indentation is 4 spaces.
• Braces appear on the same line as function, try/catch, array declaration, etc. blocks.
• 'else', 'catch' and other such statements start on the same line as the closing brace for the if/try
• Wrapping is left to the developer since not all code looks clean wrapped (and neither does all code look good unwrapped)
• Import individual classes rather than entire packages.

Sample code block:

import java.util.Date;

/**
 * Sample class to demo formatting standard for IcedTea Web
 */

class Sample {

    /** Sample array of ints */
    int[] sampleArray = { 1, 0 };

    /** Something to tell the world */
    String str = "Hello World";

    /** I can't think of why this is here */
    HashMap<String, Integer> strMap = new HashMap<String, Integer>();

    /**
     * Function foo that does something earth shattering!
     *
     * @param a The parameter that changes the world
     */
    public void foo(int a) {

        // Decide how the world is to be changed
        switch (a) {
            case 0:
                foo2(0);
                break;
            default:
                foo3();
        }
        
        try {
            exceptionThrowingFoo();
        } catch (FooException fe) {
            // Do something
        }

        for (int i = 0; i < 5; i++) {
            foo2(i);
        }

        for (String key : strMap.keySet()) {
            /* ... */
        }

    }

    public void foo2(int i) {
        /* ... */
    }

    public void foo3() {
        /* ... */
    }
}

9 Release Plans

9.1 IcedTea-Web 1.0 (Released: Feb 2 2011)

9.2 IcedTea-Web 1.1

Released: Jun 8th 2011) Tracker Bug

9.3 IcedTea-Web 1.2

9.4 IcedTea-Web 1.3

Released September 5, 2012

9.5 IcedTea-Web 1.4

Released 4th May 2013 - announcement

9.6 IcedTea-Web 1.5

Released 7th April 2014 - announcement

notes:

- with "Check HTML parsing feasibility" done, the tagsoup is recomanded dependence for icedtea-web
- with logging rework, all messgaes in ITW must go out through OutputController.getLogger().log in java and via PLUGIN_DEBUG, PLUGIN_ERROR macros in C++ part
- with resurrected console were added (in addition to specification) possibilities to show only for plugin and to show only for javaws
- with improved logging file and stdout/err logs are working, console is accessible from error dialogues, unified debug options via itw-settings and environment variables both for plugin and javaws
- linux logging is now supported for most critical errors
- new binary - policyeditor

9.7 IcedTea-Web 1.6

released 29.4.2015
And for record:
1.6.1 http://mail.openjdk.java.net/pipermail/distro-pkg-dev/2015-September/033546.html
1.6.2 http://mail.openjdk.java.net/pipermail/distro-pkg-dev/2016-February/034831.html

notes:

- fixed offline is changing way how desktop icons are handled.All desktop icons generated with 1.5.0 and older, should be removed, and regenerated
- new experimental -html switch for javaws which allows lunch applet(s) without browser at all

9.8 IcedTea-Web 1.7

9.9 IcedTea-Web 1.8

9.10 Future IcedTea-Web tasks

10 Debugging

Both javaws and plugin can be configured to allow a remote java debugger to connect and debug the Java code.

javaws accepts a -Xnofork argument to avoid forking. javaws also accepts arguments to pass to the JVM using -J as in -Jactual_jvm_arg_here. Use it like this:

javaws -J-Xdebug -J-Xnoagent -J-Xrunjdwp:transport=dt_socket,address=8787,server=y,suspend=y -Xnofork http://example.com/a.jnlp

For the plugin, set the envionment variable ICEDTEAPLUGIN_DEBUG to true to make it listen for debugger connections on port 8787. If you are trying to debug initialization code, set it to suspend instead - this will make the JVM suspend on startup and wait for a debugger to connect.

11 Developing with Eclipse

Follow this guide to set up eclipse for development: Developing with Eclipse.

12 Architecture

In IcedTea-Web, each application or applet is executed under a different AppContext. This allows the client application to have a different look and feel from the rest of IcedTea-Web. It means we can have IcedTea-Web's dialogs show up using a different look and feel compared to the rest of the application. It also means each applet running in the browser can have a different look and feel. More gory details are available at [3]

12.1 Netx Architecture

The Netx source is located under netx. It is implemented completely in Java. The starting point is net.sourceforge.jnlp.runtime.Boot. Various subpackages of net.sourceforge.jnlp implement different parts of JNLP.

Roughly, this is the typical operation of Netx:

1. Parse options and arguments (net.sourceforge.jnlp.runtime.Boot)
2. Download the JNLP file if it is not local (net.sourceforge.jnlp.JNLPFile)
3. Parse the JNLP file (net.sourceforge.jnlp.Parser)
4. Create a new JVM if required (for example, if the JNLP application wants a larger max heap size) (net.sourceforge.jnlp.Launcher)
5. Create a new ThreadGroup for the application (and create an appropriate AppContext for it) (net.sourceforge.jnlp.Launcher)
6. Create a new ClassLoader to download and check resources needed by the JNLP (net.sourceforge.jnlp.runtime.JNLPClassLoader)
7. Verify all jars (net.sourceforge.jnlp.runtime.JNLPClassLoader, net.sourceforge.jnlp.tools.JarSigner)
8. Prompt user in case of security issues (net.sourceforge.jnlp.security.*)
9. Extract nested jars or native libraries contained in the downloaded jars (net.sourceforge.jnlp.runtime.JNLPClassLoader)
10. Start the main method (net.sourceforge.jnlp.Launcher)

Some more information may also be found in the FOSDEM 2011 presentation (Alternate link)

12.2 Plugin Architecture

The plugin source is located under plugin. There are two components that work together to make the plugin function: a C++ browser component and a Java component. The browser component is a dynamic library that is loaded by the browser. This library the creates FIFO pipes and starts the JVM. The browser component then coordinates with the JVM to load and run the component, as well as allowing JavaScript code to interact with Java code via LiveConnect.

Some documentation describing the plugin architecture is available at http://icedtea.classpath.org/hg/icedtea-web/file/tip/plugin/docs/

Once the plugin reaches the Java side, it sets out a series of calls, starting multiple threads. This image shows the high level path the JVM takes when running an applet. Note that the image only depicts the major steps that lead to the running of each thread; there is more functionality within the rest of the methods.

12.3 New os.arch namespace Architecture

IcedTea-Web provide javaws and plugin support to many new OS architecture and ABI combinations. This calls for the need of a redesigned os.arch namespace Architecture to support loading of native JNI in JNLP and Applets. Currently under discussion: New os.arch namespace Architecture.

13 Security Notes

13.1 Introduction

The official documentation on plugin/javaws security is spotty at best - especially when you get to non-trival cases. In a lot of cases, the policy is defined in a way that existing applications don't break - this tends to make the security policy more complex than needed. This page attempts to describe the security policies/models used by IcedTea-Web, with notes where this policy is different from that of the proprietary plugin/javaws.

13.2 Same Origin Policy

The idea behind Same Origin Policy is that only things (code, web pages) which originate from the same location can interact with each other. In the case of the plugin, Same Origin Policy says that applets that originate from the same source can interact with each other.

But what is the "source"? The 'codebase' attribute, if it is a complete URL, is used as the source. Otherwise it is appended to the web page URL and used as the source. As a fallback (if codebase is not used) the web page URL is the source.

13.3 Signed Application/Applet

A signed application/applet consists of JARs that are all signed. For browser/plugin applets, partial signing is allowed. This means that only some of the applet JARs have signing, and/or that there are classes used by the applet which are not loaded out of a JAR at all, and are instead loaded directly from the codebase.

An applet's JARs can be signed by different certificates. For JNLP files, the situation is slightly more complex: all JARs referenced from a single JNLP must be signed by the same certificate. This means that applications that consist of multiple JNLPs (main JNLP and extensions) can be signed by different certificates. In fact, it's possible to have a main JNLP that's unsigned and extension JNLPs that are signed - the situation quickly becomes very complex.

13.4 Signed Entires in JARs

All files in a JAR should be signed, other than those located in the META-INF/ folder. If only part of a JAR is signed, IcedTea-Web may run normally, abort, prompt the user, or continue in sandbox.

The following shows IcedTea-Web's behaviour for various scenarios:

JNLP

Browser

13.5 ClassLoader Sharing

To share classloaders between applets, the codebase, cache_archive, java_archive and archive attributes/params must have the same values [4] .

13.6 Certificates

If certificates have timestamps, then expiration/revocation warning will not be shown if the jar signature timestamp is before the expiration/revocation [5] .

13.7 Browser KeyStores

The plugin/webstart use jss to integrate with the browser's keystores [6]

13.8 Classpath Usage in Manifests

Apple resources are allowed to specify classpath entries in their manifests. These will be brought into the classloader at runtime. This rule is only followed given that no JNLP is being used. In other words, applets run in the plugin using jnlp_href or applets using webstart will not search classpath entries. The proprietary plugin has made an exception for jnlp_href applets. However, IcedTea-Web has chosen to disallow this searching.

13.9 HTTPS Certificates

If an HTTPS certificate cannot verified, namely it does not have an already trusted signer or CA, the user is prompted with a dialog to allow the application to continue. If it is verifiable, the application will continue normally, without prompting the user for confirmation.

13.10 Other notes on security

Browser Security Handbook: Same Origin Policy For Java

13.11 Applets extended security

After several exploits in 2012/2013 to Java through proprietary plugin (some of which were possible via icedtea-web as well) Oracle decided to add click-to-play functionality to their plugin. To keep this illusion of security IcedTea-Web, has to follow. The implementation of this feature is described here.

13.12 Custom Policies and Run In Sandbox

As of release 1.5, fully and partially signed applets can now be run without granting them All-Permission. This is achieved by clicking the "Sandbox" button on the security dialogs which appear before these applets start. Clicking this button, as opposed to the standard "Run/Proceed" button, causes the current applet to be run with reduced permissions. Exactly which permissions are granted is also configurable. See Custom Policies and PolicyEditor for more information.

13.13 Policy Editor

Also as of release 1.5, IcedTea-Web includes a utility called PolicyEditor. This is a GUI tool (command name: policyeditor) which allows end users to quickly and easily view or edit the contents of their applet policy file. This provides a mechanism for allowing certain applets to run with some elevated privileges, without allowing the applets all privileges. For more information, see the dedicated PolicyEditor page here.

14 Other Resources

• Bugzilla
• IcedTea-Web mailing list
• Release-testing guide