Migrating from Resin 3.0 to Resin 4.0

From Resin 3.0

(Difference between revisions)
Jump to: navigation, search
m (Migrating from Resin 3.x to Resin 4.0 moved to Migrating from Resin 3.0 to Resin 4.0: Splitting into 3.0 and 3.1 migration pages)
(→Resin Data Directory)
 
(45 intermediate revisions by 2 users not shown)
Line 3: Line 3:
  
 
# The required JDK version is now Java 1.6.  As of this writing, Java 1.5 and earlier have reached the end of service life.  Make sure you use the JDK -- the JRE is not sufficient.
 
# The required JDK version is now Java 1.6.  As of this writing, Java 1.5 and earlier have reached the end of service life.  Make sure you use the JDK -- the JRE is not sufficient.
−
# The [http://caucho.com/resin/install/install.xtp build process] for compiling the Resin JNI and installing Resin have changed.  Before Resin 4.0, you would install Resin by unpacking the distribution directly in the filesystem.  Resin 4.0's configure script now creates makefiles that install all the necessary files in standard locations for Linux/Unix.  There is also a .deb package for Ubuntu available.  Windows installation is unchanged.
+
# The [http://caucho.com/resin-4.0/install/install.xtp build process] for compiling the Resin JNI and installing Resin have changed.  Before Resin 4.0, you would install Resin by unpacking the distribution directly in the filesystem.  Resin 4.0's configure script now creates makefiles that install all the necessary files in standard locations for Linux/Unix.  There is also a .deb package for Ubuntu available.  Windows installation is unchanged.
 
# The main configuration file has been renamed from resin.conf to resin.xml.
 
# The main configuration file has been renamed from resin.conf to resin.xml.
  
Line 9: Line 9:
  
 
=Migrating from Resin 3.0=
 
=Migrating from Resin 3.0=
 +
 +
After Resin 4 is installed you should be able to verify default installation by launching Resin with either ''resin.exe'' for Windows or ''/etc/init.d/resin start'' on Linux. If installed on Mac OSX, Resin can be by executing ''bin/resin start' from 'Resin Home' directory.
 +
 +
By default Resin serves http on port 8080 and provides default welcome page which should be accessible at http://localhost:8080/.
 +
 +
==Directories Layout==
 +
By default resin operates on the following directories and scripts.
 +
{| class="wikitable" border="1" style="border-collapse:collapse;" width="100%"
 +
|-
 +
! Directory
 +
! Description
 +
|-
 +
|Resin Home
 +
| directory where Resin's binaries are installed
 +
|-
 +
| Resin Root
 +
| directory where Resin's operational directories are located
 +
|-
 +
| Resin Log     
 +
| directory where Resin's server logs are located
 +
|-
 +
| Resin Configuration
 +
| directory where Resin's configuration is located
 +
|-
 +
| Resin start script
 +
| startup script
 +
|}
 +
 +
Depending on your system this directories can be found in the following locations:
 +
 +
'''On Windows, OSX and installations made with unarchiving Resin's distributive'''
 +
 +
"Resin Home" and "Resin Root" is the directory where Resin was unarchived. This type of installation keeps all related Resin files in one location. "Resin Log" and "Resin Configuration" directories will reside in Resin's Home directory. 'Resin start script' will be located in bin directory inside "Resin Home".
 +
 +
'''On Linux(*nix) using .deb, .rpm or './configure; make; make install' with default settings'''
 +
{| class="wikitable" border="1" style="border-collapse:collapse;" width="100%"
 +
|-
 +
! Directory
 +
! Description
 +
|-
 +
|Resin Home
 +
|/usr/local/share/resin-${version}
 +
|-
 +
|Resin Root
 +
|/var/resin
 +
|-
 +
|Resin Log
 +
|/var/log/resin
 +
|-
 +
|Resin Configuration
 +
|/etc/resin
 +
|-
 +
|Resin start script
 +
|/etc/init.d/resin
 +
|}
 +
 +
===Resin Home Directory===
 +
Resin Home is a directory where Resin installs its binary files (see 'Directories Layout' section for its location)
 +
 +
{| class="wikitable" border="1" style="border-collapse:collapse;" width="100%"
 +
! Directory
 +
! Description
 +
|-
 +
|bin
 +
|Resin startup scripts
 +
|-
 +
|lib
 +
|Resin jar files
 +
|-
 +
|libexec64
 +
|Resin JNI performance pack (*nix)
 +
|-
 +
|win32
 +
|Resin JNI performance pack (windows 32 bit)
 +
|-
 +
|win64
 +
|Resin JNI performance pack (windows 64 bit)
 +
|-
 +
|}
 +
 +
===Resin Root Directory===
 +
'Resin Root' contains Resin's operational data (see 'Directories Layout' section for its location). 'Virtual Hosts', 'Web Applications', 'User Sessions' and 'Web Cache' data will be stored in 'Resin Root' directory and their respective subdirectories listed below:
 +
 +
{| class="wikitable" border="1" style="border-collapse:collapse;" width="100%"
 +
! Directory
 +
! Description
 +
|-
 +
|webapps
 +
|contains web applications deployed to default host
 +
|-
 +
|resin-data
 +
|contains stored User Sessions, server stats and cache
 +
|-
 +
|watchdog-data
 +
|contains lock file for watchdog
 +
|-
 +
|doc
 +
|contains Resin Admin Application and Resin Documentation
 +
|-
 +
|}
 +
===Resin Data Directory===
 +
Resin data directory contains .git repository with deployed applications, distcache (sessions), logs and runtime statistics databases. Resin-data directory can be deleted to reset state of the server to a clean state. To leave the deployed applications intact .git directory should not be deleted.
 +
 +
===Configuration Files===
 +
Resin has changed configuration to use .xml extension instead of using extension .conf and introduced a file with externalizes properties. Further, it splits out cluster configuration into cluster-default.xml. The new health functionality is configured in health.xml file.
 +
 +
Default Resin configuration directory will have the following files:
 +
 +
{| class="wikitable" border="1" style="border-collapse:collapse;" width="100%"
 +
!File
 +
!Description
 +
|-
 +
| resin.xml
 +
| main Resin configuration file
 +
|
 +
|-
 +
| resin.properties
 +
| externalized properties (imported from resin.xml)
 +
|-
 +
| app-default.xml
 +
| default web application configuration (imported from resin.xml)
 +
|-
 +
| cluster-default.xml
 +
| default cluster configuration  (imported from resin.xml)
 +
|-
 +
| health.xml
 +
| health watch configuration (imported from resin.xml)
 +
|}
 +
 +
===Resin executables, startup scripts===
 +
Resin provides a number of scripts for starting manually or as a service for Linux or Windows.
 +
 +
{| class="wikitable" border="1" style="border-collapse:collapse;" width="100%"
 +
!File (absolute or relative to Resin Home)
 +
!Description
 +
|-
 +
| /etc/init.d/resin
 +
| *nix start up script
 +
|-
 +
| resin.exe
 +
| starts Resin on Windows in a standalone mode or as a service
 +
|-
 +
| setup.exe
 +
| configures Windows Service. Resin service is implemented in resin.exe
 +
|-
 +
| bin/resinctl
 +
| resin CLI script for running resin commands
 +
|-
 +
| contrib/MacOSX/resin.plist
 +
| resin startup script for MacOSX (requires editing)
 +
|-
 +
| contrib/FreeBSD/resin
 +
| resin startup script for FreeBSD (requires editing)
 +
|}
 +
 +
==Resin Command Line==
 +
Resin 4.0 provides extended set of commands. It also changes the existing commands adding new options and flags. If you are migrating the CLI for Resin 4 should be treated as new.
 +
{| class="wikitable" border="1" style="border-collapse:collapse;" width="100%"
 +
!Command
 +
!Description
 +
|-
 +
!colspan="2"|Starting and stopping Resin
 +
|-
 +
|start
 +
|starts a Resin server
 +
|-
 +
|start-all
 +
|starts all servers listening to the machine's IP interfaces
 +
|-
 +
|start-with-foreground
 +
|starts the watchdog in foreground mode (for MacOS-X)
 +
|-
 +
|console
 +
|start Resin in console mode
 +
|-
 +
|gui
 +
|starts a Resin server with a GUI control
 +
|-
 +
|restart
 +
|restarts a Resin server
 +
|-
 +
|kill
 +
|forces a kill of a Resin server
 +
|-
 +
|stop
 +
|stop a Resin server
 +
|-
 +
|shutdown
 +
|shuts down the watchdog and all its managed Resin servers
 +
|-
 +
|disable
 +
|disables a server for http /load-balancing (Resin-Pro)
 +
|-
 +
|disable-soft
 +
|allows existing sessions to finish and disables the server (Resin-Pro)
 +
|-
 +
|enable
 +
|enables a server for http /load-balancing (Resin-Pro)
 +
|-
 +
!colspan="2"|Web application management
 +
|-
 +
|web-app-deploy
 +
|deploys an application
 +
|-
 +
|web-app-restart
 +
|restarts a deployed application
 +
|-
 +
|web-app-restart-cluster
 +
|restarts a deployed application
 +
|-
 +
|web-app-start
 +
|starts a deployed application
 +
|-
 +
|web-app-stop
 +
|stops a deployed application
 +
|-
 +
|web-app-undeploy
 +
|undeploys an application
 +
|-
 +
|deploy
 +
|deploys an application
 +
|-
 +
|deploy-cat
 +
|pulls a deployed web-app file
 +
|-
 +
|deploy-copy
 +
|copies a deployment to a new tag name
 +
|-
 +
|deploy-list
 +
|lists deployed applications
 +
|-
 +
|deploy-ls
 +
|lists deployed web-app files
 +
|-
 +
|undeploy
 +
|undeploys an application
 +
|-
 +
!colspan="2"|Configuration management
 +
|-
 +
|config-cat
 +
|pulls a configuration file
 +
|-
 +
|config-deploy
 +
|deploys a configuration directory or jar file
 +
|-
 +
|config-ls
 +
|lists the configuration files
 +
|-
 +
|config-undeploy
 +
|undeploys configuration
 +
|-
 +
!colspan="2"|Trouble shooting
 +
|-
 +
|heap-dump
 +
|produces a JVM memory heap dump
 +
|-
 +
|pdf-report
 +
|creates a PDF report of a Resin server (Resin-Pro)
 +
|-
 +
|profile
 +
|gathers a CPU profile of a running server (Resin-Pro)
 +
|-
 +
|scoreboard
 +
|produces a concise thread activity report for groups of related threads (Resin-Pro)
 +
|-
 +
|status
 +
|watchdog and server status
 +
|-
 +
|thread-dump
 +
|displays a JVM thread dump summary
 +
|-
 +
|list-restarts
 +
|lists the most recent Resin server restart times (Resin-Pro)
 +
|-
 +
!colspan="2"|JMX management
 +
|-
 +
|jmx-call
 +
|calls a JMX operation on a server MBean (Resin-Pro)
 +
|-
 +
|jmx-dump
 +
|dumps all JMX values from a Resin server (Resin-Pro)
 +
|-
 +
|jmx-list
 +
|lists the JMX MBeans in a Resin server (Resin-Pro)
 +
|-
 +
|jmx-set
 +
|sets a JMX value for a server MBean (Resin-Pro)
 +
|-
 +
!colspan="2"|Misc
 +
|-
 +
|jspc
 +
|pre-compiles JSP files
 +
|-
 +
|license-add
 +
|adds a Resin-Professional license to an installation
 +
|-
 +
|log-level
 +
|sets the java.util.logging level for debugging (Resin-Pro)
 +
|-
 +
|password-encrypt
 +
|encrypts a password
 +
|-
 +
|password-generate
 +
|generates an administrator user and password
 +
|-
 +
|watchdog
 +
|(deprecated) starts the watchdog in foreground mode (MacOS-X)
 +
|-
 +
|help <command>
 +
|prints command usage message
 +
|-
 +
|version
 +
|prints version
 +
|}
 +
 +
Resin remote commands require specifying login name and password. Please see [[#Resin_Admin_Web_Console|Resin Admin]] section for details.
 +
 +
==Resin Administration==
 +
Resin 4.0 provides major improvements for Administrators, Dev Ops and Developers. These improvements are available in a Resin Health System which is  a new addition and via updates to Resin Admin Interface and CLI.
 +
 +
===Resin Health System===
 +
Resin Health System is a new addition in Resin 4.0. This system will act to determine if the Applications running on Resin affect functioning of Resin or JVM in a manner that will produce hard crashes and prevent these crashes by making a manageable restart. A restart action taken before the servers runs into an unresponsive state is a preferred way of restoring services as fast as possible. A manageable restart also gives applications change to finish their shutdown routines correctly.
 +
 +
To provide for this capability Resin's Health system takes various metrics and compares them to critical values. When metrics become critical the Resin will stop applications and restart.
 +
 +
The health checks will also issue alerts using log or email when tested parameters change abruptly. For example, when rate of new thread or file descriptor allocation increase beyond configured value, or server starts running out of memory and alert will be issued.
 +
 +
In addition to the alerts, an extended action can be configured to aid in debugging. Such a Thread Snapshot or a Heap dump action can be configured to run before the JVM becomes too busy or unresponsive.
 +
 +
The health system itself is configured with a HealthSystem tag in health.xml file.
 +
 +
====Resin Health CLI====
 +
Resin CLI is extended to provide commands to do the following
 +
<ul>
 +
<li>Produce Server PDF reports</li>
 +
<li>Produce Heap snapshots</li>
 +
<li>Produce Thread snapshots</li>
 +
<li>Produce Network score board</li>
 +
</ul>
 +
 +
===Resin Admin Web Console===
 +
Resin Admin Web Console is extended to represent metrics taken with the meters configured in Resin Health. Such new meters include the following:
 +
 +
<ul>
 +
<li>CPU loads</li>
 +
<li>CPU context switch counts</li>
 +
<li>Physical and JVM Memory</li>
 +
<li>JVM GC stats</li>
 +
<li>Thread Pool stats</li>
 +
<li>Request Elapsed Time, Counts and Error Counts</li>
 +
<li>Net stats for Resin ports</li>
 +
<li>File Descriptos</li>
 +
<li>Database Pool stats</li>
 +
<li>Proxy Cache stats</li>
 +
<li>Invocation stats</li>
 +
</ul>
 +
 +
Resin Admin requires a login. Creating a user name and password can be done using Resin CLI with the following steps.
 +
<ul>
 +
<li>open console</li>
 +
<li>use bin/resin.sh or bin/resinctl to create a username and password pair</li>
 +
<li>update conf/resin.properties and set user name and password for admin</li>
 +
</ul>
 +
 
 +
  bin/resin.sh generate-password --user admin
 +
  Enter password: ********
 +
  Verify password: ********
 +
  admin_user : admin
 +
  admin_password : {SSHA}hw5/oasdkjfl32j4p4irefwldskdjfoi
 +
 +
After Resin admin_user and admin_password are printed they can be pasted into resin.properties
 +
 
==Starting Resin==
 
==Starting Resin==
−
One of the major changes from Resin 3.0 to Resin 4.0 is the introduction of the [http://caucho.com/resin/admin/watchdog.xtp Resin Watchdog] which changes the way in which Resin is started and managed during runtime.  The httpd.sh and httpd.exe executables no longer exist.  The Watchdog documentation linked above has in-depth details, but essentially Resin now runs with two Java processes, the main Resin process and the Watchdog.  This architecture introduces many advantages for management and reliability, but changes the way that Resin is started and how the Java process is managed.
+
One of the major changes from Resin 3.0 to Resin 4.0 is the introduction of the [http://caucho.com/resin-4.0/admin/watchdog.xtp Resin Watchdog] which changes the way in which Resin is started and managed during runtime.  The httpd.sh and httpd.exe executables no longer exist.  The Watchdog documentation linked above has in-depth details, but essentially Resin now runs with two Java processes, the main Resin process and the Watchdog.  This architecture introduces many advantages for management and reliability, but changes the way that Resin is started and how the Java process is managed.
  
 
Example Resin 4.0 command line  
 
Example Resin 4.0 command line  
Line 57: Line 429:
  
 
==Converting clustered setups==
 
==Converting clustered setups==
−
Clustering in Resin 4.0 is drastically different from that of Resin 3.x.  Though conversion is required, the resultant configuration file is more understandable and the capabilities are greater. In Resin 4.0, a cluster is a collection of servers that serve a set of virtual hosts. For each virtual host, there are a number of web-apps.  The configuration of Resin 4.0 follows this model, with the resin.xml file having roughly the following outline:
+
Resin 4.0 provides clustering for session replication and failover similar to Resin 3 with the main difference that a cluster now provides triplicate copy of data and dynamic servers capabilities. Triplicate copy is achieved by configuring a cluster with at least three servers. Dynamic servers can be added or removed from the
 +
cluster on as needed basis using Resin CLI.  
  
−
  &lt;resin>
+
Resin 4.0 cluster configuration resides in resin.xml. By default resin.xml configures two main clusters: web and app clustered. Web cluster can be used as a load balancer. It is not required to run Web cluster, but running it as a load balancer will make sure that sticky sessions work as expected and that content caching is used to improve the performance of the overall solution. Web cluster normally should not have any applications deployed on it. It is used purely for load balancing, sticky sessions and content caching.
−
    &lt;cluster id="app">
+
−
      &lt;server>...&lt;/server>
+
−
      &lt;server>...&lt;/server>
+
−
     
+
−
      &lt;host id="">
+
−
        &lt;web-app>
+
−
          ...
+
−
        &lt;/web-app>
+
−
      &lt;/host>
+
−
    &lt;/cluster>
+
−
   
+
−
    &lt;cluster id="web">
+
−
      ...
+
−
    &lt;/cluster>
+
−
  &lt;/resin>
+
  
−
Notice that &lt;server> is now a child of &lt;cluster> instead of the other way around (clusters contain a set of servers) and that the &lt;srun> tag has disappeared.  &lt;host> tags are now side-by-side &lt;server> tags as well, instead of the &lt;host> being a child of &lt;server>.  Think of servers as representing a Resin instance and all the configuration that goes along with that (e.g. JVM arguments, ports, ip addresses, etc.). Hosts are collections of web-apps. A cluster then organizes servers and hosts together to show which instances serve which content.
+
App cluster is used to host web applications. Web cluster is configured to tunnel requests to application servers in App cluster. Web cluster should be able to access servers in the app cluster using port 6800 (Resin server port).
 +
 
 +
Resin.xml in version 4.0 extracts server configuration for app and web clusters into conf/resin.properties.
 +
 
 +
resin.properties uses app_servers property to configure the core three servers. Three core servers make up a triad which is provides triplicate copy of the data (sessions and distributed cache)
 +
 
 +
  # app-tier Triad servers: app-0 app-1 app-2
 +
  app_servers      : 192.168.1.10:6800 192.168.1.11:6800 192.168.1.12:6800
 +
 
 +
The three servers receive ids based on the cluster name 'app' and position in the app_servers value. Such server 192.168.1.10 will be assigned server id of app-0.
 +
 
 +
Additionally you can change http ports in the HTTP section of the resin.properties as so:
 +
 
 +
  app.http = 8080
 +
 
 +
To set http port for specific server app-{id}.http property key can be used as so:
 +
 
 +
  app-0.http = 8082
 +
 
 +
This becomes especially useful if Resin servers run in one virtual or physical environment.
 +
 
 +
Likewise, the web tier servers are configured with key web_servers.
 +
 
 +
Keep in mind that keys can have any names and be imported from resin.xml as ${key}, which gets replaced with the key's value .e.g.
 +
 
 +
  <server-multi id-prefix="app-" address-list="${app_servers}" port="6800"/>
 +
 
 +
&lt;server-multi>tag is a new tag which replaces replace multiple &lt;server> tags in default configuration.
 +
 
 +
===Example: Single Server===
 +
 
 +
In Resin 4.0, all servers are part of a cluster.  '''Note that even if you're using a single server configuration, you are creating a cluster with a single server.''' 
 +
 
 +
Creating an app cluster with a single server just requires changing the IP in resin.properties:app_servers value as so:
 +
 
 +
  # app-tier Triad servers: app-0 app-1 app-2
 +
  app_servers      : 192.168.1.10:6800
 +
 
 +
===Example: Two tiers with the Resin Load Balancer===
 +
Two tiers with Resin Load balancer requires configuring app_servers and web_servers as so:
 +
 
 +
Edit resin.properties to specify servers for app tier:
 +
 
 +
  # app-tier Triad servers: app-0 app-1 app-2
 +
  app_servers      : 192.168.1.10:6800 192.168.1.11:6800
 +
 
 +
Configuring app tier with two servers splits the load in two and creates an extra copy of sessions.
 +
 
 +
Edit resin.properties to specify servers for web tier:
 +
 
 +
  # web-tier Triad servers: web-0 web-1 web-2                                                                                                                                                                   
 +
  web_servers      : 192.168.2.10:6810
 +
 
 +
Staring app and web tiers:
 +
 
 +
login into machine 192.168.1.10
 +
 
 +
  bin/resinctl start --server app-0
 +
 
 +
login into machine 192.168.1.11
 +
 
 +
  bin/resinctl start --server app-1
 +
 
 +
login into machine 192.168.2.10
 +
  bin/resin ctl start --server web-0
 +
 
 +
==Server configuration==
 +
Resin 4.0's &lt;server> tag contains a number of configuration items that were not previously configured in the Resin 3.0 &lt;srun> tag, so the two should not be considered exactly equivalent.  Specifically threading, socket, and JVM configuration is now done on a per &lt;server> basis, giving greater control for systems with heterogeneous hardware or software configurations:
 +
 
 +
* [http://www.caucho.com/resin-4.0/reference/server-tags.xtp#thread-idle-max Thread pool] (moved from &lt;resin> in Resin 3.0)
 +
* [http://www.caucho.com/resin-4.0/reference/server-tags.xtp#keepalive-max Keepalive] (moved from &lt;server> in Resin 3.0)
 +
* [http://www.caucho.com/resin-4.0/reference/server-tags.xtp#memory-free-min &lt;memory-free-min>]] (moved from &lt;resin> in Resin 3.0, renamed from &lt;min-free-memory>)
  
−
To convert an existing clustered setup to the Resin 4.0 syntax,
 
 
==Filters==
 
==Filters==
−
Rewrite filter
+
===RewriteFilter===
−
==JMS==
+
A simple [http://caucho.com/resin-3.0/servlet/filter-library.xtp#RewriteFilter RewriteFilter] was available in Resin 3.0, but has been superseded by Resin 4.0's powerful [http://www.caucho.com/resin-4.0/admin/rewrite.xtp Rewrite] mechanism.  The RewriteFilter performed much like the &lt;resin:Forward> tag of Resin 4.0, but the newer Rewrite mechanism adds redirection, request modification, and more.
 +
 
 
==Hessian==
 
==Hessian==
−
==Deprecated features==
+
The implementation of Hessian 2.0 shipped with Resin 4.0 (still in draft form) is not compatible with the earlier Hessian 2.0 draft in Resin 3.0 or with Hessian 1.0.  Make sure to update all clients and services to have matching versions.
 +
==IIS Load Balancing Filter==
 +
 
 +
Resin 4.0 provides Load Balancing Filter for IIS. Filter requires .NET framework. Filter load balances to a configured set of Resin servers. For more information on the IIS Filter proceed to [http://caucho.com/resin-4.0/admin/starting-resin-iis-7.xtp#install-configure| Installing and configuring IIS filter]
 +
 
 +
==Deprecated and removed features==
 +
* Support for Apache 1.x has been removed
 +
* Resin 3.0 configuration compatibility has been removed
 +
* Resin 3.1 rewrite tags are deprecated
 +
 
 +
==Resin IoC==
 +
The [http://www.caucho.com/resin/doc/resin-ioc.xtp Resin IoC] system has evolved from using tags such as &lt;resource> and the <tt>resin:type</tt> attribute to a more sophisticated and complete system based on JSR-299, called [http://www.caucho.com/projects/candi/ CanDI].  The basic steps to convert from a bean declared as a &lt;resource> to a CanDI bean are:
 +
 
 +
# Create a tag for your bean, using an appropriate namespace prefix (e.g. &lt;test:MyBean>)
 +
# Create a URN namespace for your class' package (e.g. xmlns:test="urn:java:com.example.test")
 +
# If you have assigned a name for your bean using the <tt>name</tt> attribute, use the [http://www.caucho.com/resin/doc/resin-ioc.xtp#@Named%20and%20bindings javax.inject.Named] annotation instead
 +
# Remove the &lt;init> tag
 +
# If you have assigned a jndi-name, use the [http://www.caucho.com/resin/doc/resin-ioc.xtp#@Resource @Resource] annotation.  (Consider removing JNDI and using type safe annotations or the @Named annotation instead.)
 +
 
 +
===Example: Basic bean configuration===
 +
<table>
 +
<tr><th>Resin 3.0 &lt;bean> configuration</th><th>Resin 4.0 CanDI configuration</th></tr>
 +
<tr>
 +
<td style='vertical-align: top; width:50%'>
 +
<pre>
 +
&lt;web-app xmlns="http://caucho.com/ns/resin">
 +
 
 +
  &lt;bean name="test">
 +
    &lt;type>com.example.test.MyBean&lt;/type>
 +
    &lt;init>
 +
      &lt;greeting>Hello&lt;/greeting>
 +
      &lt;server>${serverId}&lt;/server>
 +
      &lt;sub-bean>
 +
        &lt;value>${2 + 2}&lt;/value>
 +
      &lt;/sub-bean>
 +
    &lt;/init>
 +
  &lt;/bean>
 +
 
 +
&lt;/web-app>
 +
</pre>
 +
</td>
 +
<td style='vertical-align: top; width: 50%'>
 +
<pre>
 +
&lt;web-app xmlns="http://caucho.com/ns/resin"
 +
            xmlns:inject="urn:java:javax.inject">
  
−
==Custom types==
+
  &lt;test:MyBean xmlns:test="urn:java:com.example.test">
−
Use CanDI instead of resin:type
+
    &lt;inject:Named>test&lt;/inject:Named>
  
−
Support for Apache 1.x is deprecated
+
    &lt;test:greeting>Hello&lt;/test:greeting>
 +
    &lt;test:server>${serverId}&lt;/test:server>
 +
    &lt;test:sub-bean>
 +
      &lt;test:value>${2 + 2}&lt;/test:value>
 +
    &lt;/test:sub-bean>
 +
  &lt;/test:MyBean>
  
−
=Migrating from Resin 3.1=
+
&lt;/web-app>
−
==Starting Resin 4.0==
+
</pre>
−
For the most part, Resin 4.0 is started the same way as Resin 3.1.  One exception is if you start Resin attached to the terminal.  In general, you should run a Resin server using the "start" command, but
+
</td>
 +
</table>

Latest revision as of 16:33, 17 November 2016

Contents

[edit] Preliminaries

Before installation, there are several changes that you'll need to know in order to migrate to Resin 4.0:

  1. The required JDK version is now Java 1.6. As of this writing, Java 1.5 and earlier have reached the end of service life. Make sure you use the JDK -- the JRE is not sufficient.
  2. The build process for compiling the Resin JNI and installing Resin have changed. Before Resin 4.0, you would install Resin by unpacking the distribution directly in the filesystem. Resin 4.0's configure script now creates makefiles that install all the necessary files in standard locations for Linux/Unix. There is also a .deb package for Ubuntu available. Windows installation is unchanged.
  3. The main configuration file has been renamed from resin.conf to resin.xml.

As a general recommendation for migration, we suggest starting with a clean installation of Resin 4.0, including using the sample configuration. By beginning with the sample configuration and modifying it to match your deployment setup, you'll be much more likely to configure the server correctly. This approach is usually much easier than starting with your existing configuration and modifying to make it compatible with the new version.

[edit] Migrating from Resin 3.0

After Resin 4 is installed you should be able to verify default installation by launching Resin with either resin.exe for Windows or /etc/init.d/resin start on Linux. If installed on Mac OSX, Resin can be by executing bin/resin start' from 'Resin Home' directory.

By default Resin serves http on port 8080 and provides default welcome page which should be accessible at http://localhost:8080/.

[edit] Directories Layout

By default resin operates on the following directories and scripts.

Directory Description
Resin Home directory where Resin's binaries are installed
Resin Root directory where Resin's operational directories are located
Resin Log directory where Resin's server logs are located
Resin Configuration directory where Resin's configuration is located
Resin start script startup script

Depending on your system this directories can be found in the following locations:

On Windows, OSX and installations made with unarchiving Resin's distributive

"Resin Home" and "Resin Root" is the directory where Resin was unarchived. This type of installation keeps all related Resin files in one location. "Resin Log" and "Resin Configuration" directories will reside in Resin's Home directory. 'Resin start script' will be located in bin directory inside "Resin Home".

On Linux(*nix) using .deb, .rpm or './configure; make; make install' with default settings

Directory Description
Resin Home /usr/local/share/resin-${version}
Resin Root /var/resin
Resin Log /var/log/resin
Resin Configuration /etc/resin
Resin start script /etc/init.d/resin

[edit] Resin Home Directory

Resin Home is a directory where Resin installs its binary files (see 'Directories Layout' section for its location)

Directory Description
bin Resin startup scripts
lib Resin jar files
libexec64 Resin JNI performance pack (*nix)
win32 Resin JNI performance pack (windows 32 bit)
win64 Resin JNI performance pack (windows 64 bit)

[edit] Resin Root Directory

'Resin Root' contains Resin's operational data (see 'Directories Layout' section for its location). 'Virtual Hosts', 'Web Applications', 'User Sessions' and 'Web Cache' data will be stored in 'Resin Root' directory and their respective subdirectories listed below:

Directory Description
webapps contains web applications deployed to default host
resin-data contains stored User Sessions, server stats and cache
watchdog-data contains lock file for watchdog
doc contains Resin Admin Application and Resin Documentation

[edit] Resin Data Directory

Resin data directory contains .git repository with deployed applications, distcache (sessions), logs and runtime statistics databases. Resin-data directory can be deleted to reset state of the server to a clean state. To leave the deployed applications intact .git directory should not be deleted.

[edit] Configuration Files

Resin has changed configuration to use .xml extension instead of using extension .conf and introduced a file with externalizes properties. Further, it splits out cluster configuration into cluster-default.xml. The new health functionality is configured in health.xml file.

Default Resin configuration directory will have the following files:

File Description
resin.xml main Resin configuration file
resin.properties externalized properties (imported from resin.xml)
app-default.xml default web application configuration (imported from resin.xml)
cluster-default.xml default cluster configuration (imported from resin.xml)
health.xml health watch configuration (imported from resin.xml)

[edit] Resin executables, startup scripts

Resin provides a number of scripts for starting manually or as a service for Linux or Windows.

File (absolute or relative to Resin Home) Description
/etc/init.d/resin *nix start up script
resin.exe starts Resin on Windows in a standalone mode or as a service
setup.exe configures Windows Service. Resin service is implemented in resin.exe
bin/resinctl resin CLI script for running resin commands
contrib/MacOSX/resin.plist resin startup script for MacOSX (requires editing)
contrib/FreeBSD/resin resin startup script for FreeBSD (requires editing)

[edit] Resin Command Line

Resin 4.0 provides extended set of commands. It also changes the existing commands adding new options and flags. If you are migrating the CLI for Resin 4 should be treated as new.

Command Description
Starting and stopping Resin
start starts a Resin server
start-all starts all servers listening to the machine's IP interfaces
start-with-foreground starts the watchdog in foreground mode (for MacOS-X)
console start Resin in console mode
gui starts a Resin server with a GUI control
restart restarts a Resin server
kill forces a kill of a Resin server
stop stop a Resin server
shutdown shuts down the watchdog and all its managed Resin servers
disable disables a server for http /load-balancing (Resin-Pro)
disable-soft allows existing sessions to finish and disables the server (Resin-Pro)
enable enables a server for http /load-balancing (Resin-Pro)
Web application management
web-app-deploy deploys an application
web-app-restart restarts a deployed application
web-app-restart-cluster restarts a deployed application
web-app-start starts a deployed application
web-app-stop stops a deployed application
web-app-undeploy undeploys an application
deploy deploys an application
deploy-cat pulls a deployed web-app file
deploy-copy copies a deployment to a new tag name
deploy-list lists deployed applications
deploy-ls lists deployed web-app files
undeploy undeploys an application
Configuration management
config-cat pulls a configuration file
config-deploy deploys a configuration directory or jar file
config-ls lists the configuration files
config-undeploy undeploys configuration
Trouble shooting
heap-dump produces a JVM memory heap dump
pdf-report creates a PDF report of a Resin server (Resin-Pro)
profile gathers a CPU profile of a running server (Resin-Pro)
scoreboard produces a concise thread activity report for groups of related threads (Resin-Pro)
status watchdog and server status
thread-dump displays a JVM thread dump summary
list-restarts lists the most recent Resin server restart times (Resin-Pro)
JMX management
jmx-call calls a JMX operation on a server MBean (Resin-Pro)
jmx-dump dumps all JMX values from a Resin server (Resin-Pro)
jmx-list lists the JMX MBeans in a Resin server (Resin-Pro)
jmx-set sets a JMX value for a server MBean (Resin-Pro)
Misc
jspc pre-compiles JSP files
license-add adds a Resin-Professional license to an installation
log-level sets the java.util.logging level for debugging (Resin-Pro)
password-encrypt encrypts a password
password-generate generates an administrator user and password
watchdog (deprecated) starts the watchdog in foreground mode (MacOS-X)
help <command> prints command usage message
version prints version

Resin remote commands require specifying login name and password. Please see Resin Admin section for details.

[edit] Resin Administration

Resin 4.0 provides major improvements for Administrators, Dev Ops and Developers. These improvements are available in a Resin Health System which is a new addition and via updates to Resin Admin Interface and CLI.

[edit] Resin Health System

Resin Health System is a new addition in Resin 4.0. This system will act to determine if the Applications running on Resin affect functioning of Resin or JVM in a manner that will produce hard crashes and prevent these crashes by making a manageable restart. A restart action taken before the servers runs into an unresponsive state is a preferred way of restoring services as fast as possible. A manageable restart also gives applications change to finish their shutdown routines correctly.

To provide for this capability Resin's Health system takes various metrics and compares them to critical values. When metrics become critical the Resin will stop applications and restart.

The health checks will also issue alerts using log or email when tested parameters change abruptly. For example, when rate of new thread or file descriptor allocation increase beyond configured value, or server starts running out of memory and alert will be issued.

In addition to the alerts, an extended action can be configured to aid in debugging. Such a Thread Snapshot or a Heap dump action can be configured to run before the JVM becomes too busy or unresponsive.

The health system itself is configured with a HealthSystem tag in health.xml file.

[edit] Resin Health CLI

Resin CLI is extended to provide commands to do the following

  • Produce Server PDF reports
  • Produce Heap snapshots
  • Produce Thread snapshots
  • Produce Network score board

[edit] Resin Admin Web Console

Resin Admin Web Console is extended to represent metrics taken with the meters configured in Resin Health. Such new meters include the following:

  • CPU loads
  • CPU context switch counts
  • Physical and JVM Memory
  • JVM GC stats
  • Thread Pool stats
  • Request Elapsed Time, Counts and Error Counts
  • Net stats for Resin ports
  • File Descriptos
  • Database Pool stats
  • Proxy Cache stats
  • Invocation stats

Resin Admin requires a login. Creating a user name and password can be done using Resin CLI with the following steps.

  • open console
  • use bin/resin.sh or bin/resinctl to create a username and password pair
  • update conf/resin.properties and set user name and password for admin
 bin/resin.sh generate-password --user admin
 Enter password: ********
 Verify password: ******** 
 admin_user : admin
 admin_password : {SSHA}hw5/oasdkjfl32j4p4irefwldskdjfoi

After Resin admin_user and admin_password are printed they can be pasted into resin.properties

[edit] Starting Resin

One of the major changes from Resin 3.0 to Resin 4.0 is the introduction of the Resin Watchdog which changes the way in which Resin is started and managed during runtime. The httpd.sh and httpd.exe executables no longer exist. The Watchdog documentation linked above has in-depth details, but essentially Resin now runs with two Java processes, the main Resin process and the Watchdog. This architecture introduces many advantages for management and reliability, but changes the way that Resin is started and how the Java process is managed.

Example Resin 4.0 command line 

java -jar $RESIN_HOME/lib/resin.jar -conf /etc/resin/resin.xml -root-directory=/var/www -server app-a start

[edit] JVM arguments

JVM arguments for the main Resin process are now set within the resin.xml file instead of being passed via a script. Any JVM arguments on the command line actually go to the Watchdog process. JVM arguments can be set per server in a cluster, but in general you can set them in a <server-default> tag to apply to all servers.

For example, if you wanted to set the maximum heap size of all the Resin processes to 1GB: 

 <server-default>
   ...
   <jvm-arg>-Xmx1g</jvm-arg>

[edit] Linux/Unix

It is possible to run Resin on the console if you like for debugging or other purposes using the "console" command (instead of the "start" command as above). Note however that if you intend to run Resin as a long running process, you should not run Resin in console mode in the background. This will discard all logging sent to stdout (see the logging section below).

If you are using Linux, a sample init.d script for Resin is included with the distribution. The make install command installs it to /etc/init.d/resin. Edit the file to set the name of the server, the location of the resin.xml file, the log directory, and the root directory. Check with your distribution's documentation to see how to add the script to one or more of your runtime levels. The script may be useful for Unix as well.

Unix allows only root to bind to ports below 1024. If you use Resin as your webserver (recommended) and bind to port 80, you'll need to start Resin as root. In Resin 4.0, the Resin process can drop privileges as soon as it's bound to all its ports. You can configure the user that Resin uses in the <server> or <server-default> sections: 

 <server-default>
   ...
     <resin:if test="${resin.userName == 'root'}">
       <user-name>www-data</user-name>
       <group-name>www-data</group-name>
     </resin:if>


[edit] Windows

On Windows, Resin is now started using the resin.exe program instead of httpd.exe.

[edit] Logging

For Resin 4.0, the preferred logging method is to use java.util.logging for all output. Standard output and error are still supported, but should be used for special cases only. The <log> tag of Resin 3.x has been replaced by the <log-handler> tag in Resin 4.0. The <log-handler> can be thought of as a control on output logging, directing log messages from certain sources and of certain levels to a file (or other output stream). Conversely, the <logger> tag controls the source of log messages, controlling the logging level of individual packages. <logger> tags use the same syntax in Resin 4.0 as in 3.x, but <log> tags should be converted to <log-handler> tags. Conversion is fairly straight forward: 

 <log name="com.caucho" path="stdout:" timestamp="[%H:%M:%S.%s] "/>

becomes 

 <log-handler name="com.caucho" level="all" path="stdout:" timestamp="[%H:%M:%S.%s] "/>

This log-handler will send log messages to standard output if you run Resin on the console, but if you run Resin as a daemon process, the output will be in the directory specified by the --log-directory argument passed to the Watchdog on the command line. For example, if you set the log directory to /var/www/log and ran a server with the id "app-a", the output would be in /var/www/log/jvm-app-a.log. For the "default" server (i.e. the server with an empty string as its id), the filename will be jvm-default.log.

Similarly, the Watchdog's log will go to /var/www/log/watchdog-manager.log.

[edit] Converting clustered setups

Resin 4.0 provides clustering for session replication and failover similar to Resin 3 with the main difference that a cluster now provides triplicate copy of data and dynamic servers capabilities. Triplicate copy is achieved by configuring a cluster with at least three servers. Dynamic servers can be added or removed from the cluster on as needed basis using Resin CLI.

Resin 4.0 cluster configuration resides in resin.xml. By default resin.xml configures two main clusters: web and app clustered. Web cluster can be used as a load balancer. It is not required to run Web cluster, but running it as a load balancer will make sure that sticky sessions work as expected and that content caching is used to improve the performance of the overall solution. Web cluster normally should not have any applications deployed on it. It is used purely for load balancing, sticky sessions and content caching.

App cluster is used to host web applications. Web cluster is configured to tunnel requests to application servers in App cluster. Web cluster should be able to access servers in the app cluster using port 6800 (Resin server port).

Resin.xml in version 4.0 extracts server configuration for app and web clusters into conf/resin.properties.

resin.properties uses app_servers property to configure the core three servers. Three core servers make up a triad which is provides triplicate copy of the data (sessions and distributed cache) 

 # app-tier Triad servers: app-0 app-1 app-2
 app_servers      : 192.168.1.10:6800 192.168.1.11:6800 192.168.1.12:6800

The three servers receive ids based on the cluster name 'app' and position in the app_servers value. Such server 192.168.1.10 will be assigned server id of app-0.

Additionally you can change http ports in the HTTP section of the resin.properties as so: 

 app.http = 8080

To set http port for specific server app-{id}.http property key can be used as so: 

 app-0.http = 8082

This becomes especially useful if Resin servers run in one virtual or physical environment.

Likewise, the web tier servers are configured with key web_servers.

Keep in mind that keys can have any names and be imported from resin.xml as ${key}, which gets replaced with the key's value .e.g. 

 <server-multi id-prefix="app-" address-list="${app_servers}" port="6800"/>

<server-multi>tag is a new tag which replaces replace multiple <server> tags in default configuration.

[edit] Example: Single Server

In Resin 4.0, all servers are part of a cluster. Note that even if you're using a single server configuration, you are creating a cluster with a single server.

Creating an app cluster with a single server just requires changing the IP in resin.properties:app_servers value as so: 

 # app-tier Triad servers: app-0 app-1 app-2
 app_servers      : 192.168.1.10:6800

[edit] Example: Two tiers with the Resin Load Balancer

Two tiers with Resin Load balancer requires configuring app_servers and web_servers as so:

Edit resin.properties to specify servers for app tier: 

 # app-tier Triad servers: app-0 app-1 app-2
 app_servers      : 192.168.1.10:6800 192.168.1.11:6800

Configuring app tier with two servers splits the load in two and creates an extra copy of sessions.

Edit resin.properties to specify servers for web tier: 

 # web-tier Triad servers: web-0 web-1 web-2                                                                                                                                                                    
 web_servers      : 192.168.2.10:6810

Staring app and web tiers:

login into machine 192.168.1.10 

 bin/resinctl start --server app-0

login into machine 192.168.1.11 

 bin/resinctl start --server app-1

login into machine 192.168.2.10 

 bin/resin ctl start --server web-0

[edit] Server configuration

Resin 4.0's <server> tag contains a number of configuration items that were not previously configured in the Resin 3.0 <srun> tag, so the two should not be considered exactly equivalent. Specifically threading, socket, and JVM configuration is now done on a per <server> basis, giving greater control for systems with heterogeneous hardware or software configurations:

[edit] Filters

[edit] RewriteFilter

A simple RewriteFilter was available in Resin 3.0, but has been superseded by Resin 4.0's powerful Rewrite mechanism. The RewriteFilter performed much like the <resin:Forward> tag of Resin 4.0, but the newer Rewrite mechanism adds redirection, request modification, and more.

[edit] Hessian

The implementation of Hessian 2.0 shipped with Resin 4.0 (still in draft form) is not compatible with the earlier Hessian 2.0 draft in Resin 3.0 or with Hessian 1.0. Make sure to update all clients and services to have matching versions.

[edit] IIS Load Balancing Filter

Resin 4.0 provides Load Balancing Filter for IIS. Filter requires .NET framework. Filter load balances to a configured set of Resin servers. For more information on the IIS Filter proceed to Installing and configuring IIS filter

[edit] Deprecated and removed features

  • Support for Apache 1.x has been removed
  • Resin 3.0 configuration compatibility has been removed
  • Resin 3.1 rewrite tags are deprecated

[edit] Resin IoC

The Resin IoC system has evolved from using tags such as <resource> and the resin:type attribute to a more sophisticated and complete system based on JSR-299, called CanDI. The basic steps to convert from a bean declared as a <resource> to a CanDI bean are:

  1. Create a tag for your bean, using an appropriate namespace prefix (e.g. <test:MyBean>)
  2. Create a URN namespace for your class' package (e.g. xmlns:test="urn:java:com.example.test")
  3. If you have assigned a name for your bean using the name attribute, use the javax.inject.Named annotation instead
  4. Remove the <init> tag
  5. If you have assigned a jndi-name, use the @Resource annotation. (Consider removing JNDI and using type safe annotations or the @Named annotation instead.)

[edit] Example: Basic bean configuration

Resin 3.0 <bean> configurationResin 4.0 CanDI configuration
<web-app xmlns="http://caucho.com/ns/resin">

  <bean name="test">
    <type>com.example.test.MyBean</type>
    <init>
      <greeting>Hello</greeting>
      <server>${serverId}</server>
      <sub-bean>
        <value>${2 + 2}</value>
      </sub-bean>
    </init>
  </bean>

</web-app>

<web-app xmlns="http://caucho.com/ns/resin"
            xmlns:inject="urn:java:javax.inject">

  <test:MyBean xmlns:test="urn:java:com.example.test">
    <inject:Named>test</inject:Named>

    <test:greeting>Hello</test:greeting>
    <test:server>${serverId}</test:server>
    <test:sub-bean>
      <test:value>${2 + 2}</test:value>
    </test:sub-bean>
  </test:MyBean>

</web-app>
Retrieved from "http://wiki3.caucho.com/index.php?title=Migrating_from_Resin_3.0_to_Resin_4.0&oldid=4458"
Personal tools