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.
Contents |
Getting IcedTea-Web
You can get the icedtea-web source in several different ways.
Grab the source tarballs:
wget http://icedtea.classpath.org/download/source/icedtea-web-1.1.2.tar.gz
Anonymous clone using mercurial:
hg clone http://icedtea.classpath.org/hg/release/icedtea-web-1.1
Or try the bleeding edge:
hg clone http://icedtea.classpath.org/hg/icedtea-web
Building IcedTea-Web
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.
Testing IcedTea-Web
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 install make run-netx-dist-tests
make check will run various unit tests. Results are stored under tests.build/index_unit.html and tests.build/netx/unit/{stderr.log,stdout.log,tests-output.xml}. As of 2011-09-22, Icedtea-Web does not pass all tests - so do not fret if you get a few (~5) 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 by your own one 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 your built one. You are also likely to get lots of spurious failures as a result of trying to access classes across jars.
Before every release, we also like to run thought all the tests cases that we have collected to check for regressions.
Usage
End Users
Netx
Once the javaws binary is built and installed, it can be used by
javaws somefile.jnlp
Please see the man page (man javaws) and the help message (javaws -help) for more information.
Plugin
The plugin can be used by creating a symlink to it under a mozilla plugins directory:
cd ~/.mozilla/plugins && ln -s /path/to/icedtea/jdk/jre/lib/IcedTeaPlugin.so libjavaplugin.so
Restarting the browser should cause the plugin to be picked up by browsers. Browsers that are known to work include Firefox and Chromium. Other browsers supporting the NPAPI should work just as well.
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 inplugin.jar. -
javax.jnlp.*classes are included innetx.jar.
Please add these jars to your classpath when building.
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.
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/. Please see Java Deployment Configuration for more details.
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/ (~/.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.
Common Issues
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 distro-pkg-dev@openjdk.java.net or file a bug in the IcedTea Bugzilla.
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.
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 distro-pkg-dev@openjdk.java.net with a link to the JNLP file causing this exception.
Netx hangs while downloading an application
There are known deadlocks in downloading code. They dont happen too frequently, but if netx appears to hang while downloading an application, try killing the javaws process and starting it again.
Test Cases
Before every release, we like to run thought all the tests cases that we have collected to check for regressions.
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)
Sample code block:
/**
* 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() {
/* ... */
}
}
Release Plans
IcedTea-Web 1.0 (Released: Feb 2 2011)
| Task | Assigned To | Status |
|---|---|---|
| Stabilize build | Andrew Hughes | Done |
| Deployement configuration support | Omair Majid | Done |
| itwb-settings tool | Andrew Su | Done |
| Plugin stabilization (frame pop-up issues, race condition mitigation) | Deepak Bhole | Done |
IcedTea-Web 1.1
Released: Jun 8th 2011) Tracker Bug
| Task | Assigned To | Status |
|---|---|---|
| Cache limit | Andrew Su | Done |
| Logging support | Andrew Su | Done |
| Tracing support | Andrew Su | In progress |
| Proxy | Andrew Su | Done |
| Configuration check | Andrew Su | Done |
| Better proxy support | Omair Majid | Done |
| Command Line Control Panel | Omair Majid | Done |
| Integrate JNLPAuthenticator with rest of security dialogs | Omair Majid | Done |
| Custom policy support | Omair Majid | Done |
| Remove obsolete code (KeyTool, JarSignerResources, JarRunner) | Omair Majid | Done |
| Isolate netx.jar and plugin.jar into non JDK dir | Omair Majid | Done |
| Remove pluginappletviewer binary | Omair Majid | Done |
| Shared classloader support | Deepak Bhole | Done |
| JNLP service support via plugin (test) | Deepak Bhole | Done |
IcedTea-Web 1.2
| Task | Assigned To | Status |
|---|---|---|
| Support for npapi-sdk | Michał Górny | Done |
| OpenJDK7 support | Deepak Bhole | Done |
| Client certificate support | Lars Herschke | Done |
| Signed jnlp support | Saad Mohammad | Done |
| Add support for running with JRE only | Omair Majid | Done |
| More sensible security UI dialog (calmer icons when appropriate) | Danesh Dadachanji | Done |
IcedTea-Web 1.3
| Task | Assigned To | Status |
|---|---|---|
| jnlp_href support | Danesh Dadachanji | In progress |
| Plugin splash screen | Jiri Vanek | In progress |
| Better error notification | Jiri Vanek | Not Started |
| AWT EventQueue permissions | Omair Majid | Not Started |
| Libproxy support | Omair Majid | Not Started |
| Allow choice of JVM, JVM option specification | Andrew Su | Not Started |
| Remove in-tree copy of NanoXML; use DOM instead | Omair Majid | Not Started |
| Check HTML parsing feasibility | Omair Majid | In progress (Patch [1]) |
| Allow websites to add cookies to the Java cookie jar Bug# 588 | Deepak Bhole/Jiri Vanek | Not Started |
IcedTea-Web 2.0
| Task | Assigned To | Status |
|---|---|---|
| Custom policy editing via itwb-settings | Not yet assigned (use policy tool?) | Not Started |
| HTML parsing for jnlp files | TBD | Not Started |
| Caching subsystem replacement | Omair + ? | Not Started |
| Add missing JNLP API services | TBD | Not Started |
| Support LWJGL applets (bug 568) | Omair Majid | In progress |
| Change namespaces | TBD | Not Started |
| Work with all JDKs | Deepak Bhole | Not Started |
| New tool for .hotspotrc | Andrew Su | Not Started |
| Look into some sort of testing setup | TBD | Not Started |
| Architectural simplification (security, etc.) for easy maintenance | Deepak Bhole | Not Started |
IcedTea-Web 3.0
| Task | Assigned To | Status |
|---|---|---|
| Get rid of the custom parser in PluginAppletViewer and use a proper generic SGML/HTML parser | Deepak Bhole | Not Started |
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 -Jactul_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.
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:
- Parse options and arguments (
net.sourceforge.jnlp.runtime.Boot) - Download the JNLP file if it is not local (
net.sourceforge.jnlp.JNLPFile) - Parse the JNLP file (
net.sourceforge.jnlp.Parser) - Create a new JVM if required (for example, if the JNLP application wants a larger max heap size) (
net.sourceforge.jnlp.Launcher) - Create a new ThreadGroup for the application (and create an appropriate AppContext for it) (
net.sourceforge.jnlp.Launcher) - Create a new ClassLoader to download and check resources needed by the JNLP (
net.sourceforge.jnlp.runtime.JNLPClassLoader) - Verify all jars (
net.sourceforge.jnlp.runtime.JNLPClassLoader,net.sourceforge.jnlp.tools.JarSigner) - Prompt user in case of security issues (
net.sourceforge.jnlp.security.*) - Extract nested jars or native libraries contained in the downloaded jars (
net.sourceforge.jnlp.runtime.JNLPClassLoader) - Start the main method (
net.sourceforge.jnlp.Launcher)
Some more information may also be found in the FOSDEM 2011 presentation (Alternate link)
Plugin Architecture
The plugin source is located under plugin. There are two components that work together to make the plugin function: a 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.
Some documentation describing the plugin architecture is available at http://icedtea.classpath.org/hg/icedtea-web/file/tip/plugin/docs/
Security Notes
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 dont 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 plguin/javaws.
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"? IcedTea-Web plugin currently assumes it's the web page where the applet is embedded.
Signed Application/Applet
A signed application/applet consists of jars that are all signed.
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 extenion JNLPs that are signed - the situation quickly becomes very complex.
Signed Entires in Jars
All files in a jar must be signed - with the obvious exception of the manifest and signature-related files. This inclues non-code files and files inside the META-INF directory. If only part of a jar is signed IcedTea-Web will abort.
Currently, even an INDEX.LIST must be signed; though there has been some discussion on changing it.
ClassLoader Sharing
To share classloaders between applets, the codebase, cache_archive, java_archive and archive attributes/params must have the same values [2]
Certificates
If certificates have timestamps, then expiration/revocation warning will not be shown if the jar signature timestamp is before the expiration/revocation. [3]
Browser KeyStores
The plugin/webstart use jss to integrate with the browser's keystores [4]
Other notes on security
Browser Security Handbook: Same Origin Policy For Java
