Caucho maker of Resin Server | Application Server (Java EE Certified) and Web Server


 

Resin Documentation

home company blog docs 
app server 
 Resin Server | Application Server (Java EE Certified) and Web Server
 

resin.properties: standard configuration


Most common Resin properties are configured by resin.properties. The resin.properties variables are used by the main resin.xml configuration file.

Overview

The resin.properties file is a condensed configuration for the most common Resin configurations. Since it is a set of variables used by the main resin.xml confguration file, the variables are defined by convention. The sections following show some of the most common configurations, followed by a description of the variables.

The resin.properties is in the same directory as resin.xml. In unix systems as /etc/resin.properties. In systems deployed in a single directory, it will be ${resin.home}/conf/resin.properties.

Example: key resin.properties
...
app_servers : 127.0.0.1:6800

app.http : 8080

setuid_user : resin
setuid_group : resin

jvm_args : -Xmx2G -XX:MaxPermSize=256m
...

Qualifying properties by cluster or server

Properties can be restricted to a server or a cluster by prefixing the variable by the cluster or server name. For example, a http port can be specific to the server named 'app-0' by using app-0.http. The port can be specific to the cluster 'app' with app.http.

Example: http restrictions
http       : 8080    # default value if unspecified
app-0.http : 8081    # server 'app-0' uses 8082
app-1.http : 8082    # server 'app-0' uses 8082
app.http   : 8089    # servers in 'app' cluster use 8089
web.http   : 8090    # servers in 'web' cluster use 8090

Extending resin.properties in custom resin.xml

Because the resin.properties variables are defined by the resin.xml, sites that use their own custom resin.xml can define their own variables in their resin.xml and set those variables in the resin.properties.

For custom users, the resin.properties is read using a <resin:properties> tag in the resin.xml. The variables are used with the standard EL values.

Example: resin.xml import and use of resin.properties
<resin xmlns="http://caucho.com/ns/resin"
    xmlns:resin="urn:java:com.caucho.resin">

  <resin:properties path="${__DIR__}/resin.properties" optional="true"/>

  <dependency-check-interval>${my_var?:'2s'}</dependency-check-interval>

  ...

</resin>

The previous example defines the dependency-check-interval using a resin.properties variable my_var and a default value of 2s.

Application Server Key Properties

A basic application server configuration needs a few key properties to configure the HTTP port, the servers in the cluster, the operating system user and the JVM arguments for memory and GC.

Each server in the cluster can have the same resin.xml and resin.properties. On start, Resin will detect which server is the local one, select it and start it.

Example: key resin.properties
...
app_servers : 127.0.0.1:6800

app.http : 8080

setuid_user : resin
setuid_group : resin

jvm_args : -Xmx2G -XX:MaxPermSize=256m
...

The server names configured by app_servers are generated automatically by position: app-0, app-1, ..., app-n.

PROPERTYDESCRIPTION
app_serversA list of IP:port addresses for each server in the app-tier cluster.
app.httpThe HTTP port for each app-tier server.
setuid_userThe operating system user name for the Resin instance.
setuid_groupThe operating system group name for the Resin instance.
jvm_argsThe Java arguments for the Resin instance.

app.http configures the HTTP port for the 'app' cluster. The http defines the variable used in the resin.xml, and the app restricts it to servers in defined by app_servers. This system allows for different http ports when starting multiple servers on the same machine, like a web-tier load balancer, an app-tier server, and an memcached server.

Web Tier (Load Balancer) Key Properties

This web tier configuration has one web server that handles the HTTP, load balancing, and proxy caching, and one application server that runs the servlet applications. The web server load balances and proxies HTTP requests to the backend application cluster. To scale up, add more servers to app_servers.

Example: web-tier resin.properties
...
web_servers : 127.0.0.1:6810
web.http    : 80

proxy_cache_enable : true
proxy_cache_size   : 256m

app_servers : 127.0.0.1:6800
app.http    : 8080

setuid_user : resin
setuid_group : resin

jvm_args : -Xmx2G -XX:MaxPermSize=256m
...

The server names configured by web_servers are generated automatically by position: web-0, web-1, ..., web-n.

Example: CLI starting the servers
# resinctl start-all

The start-all command-line will start both servers in the example because both servers are listening to a local port.

Memcached Tier Key Properties

To configure Resin as a memcached server, add IP:port addresses to the memcached_servers configuration.

Example: memcached-tier resin.properties
...
memcached_servers   : 127.0.0.1:6820
memcached_port      : 11211

memcached.http      : 8080

The memcached.http is used for the /resin-admin managment and REST administration.

property reference

accept_thread_max

accept_thread_max limits the maximum threads waiting for a new connection on the port. Higher values are more resiliant to connection spikes because the idle threads are ready and waiting.

In general, the default value is reasonable and does not usually need changing.

Example: accept_thread_max
...
accept_thread_max : 32
accept_thread_min : 4
...

accept_thread_min

accept_thread_min triggers a new thread to listen for connections when the number of waiting threads drops below the limit. It works with accept_thread_max to manage the threads waiting in the accept state. Higher values can improve connection spike resposiveness.

In general, the default value is reasonable and does not usually need changing.

Example: accept_thread_min
...
accept_thread_max : 32
accept_thread_min : 4
...

admin_password

admin_password is the password used with admin_user for /resin-admin administration, REST, and remote resinctl CLI administration.

admin_password is generated with either the CLI resinctl generate-password or the /resin-admin login screen.

Example: admin_user in resin.properties
...
admin_user     : my-admin
admin_password : {SSHA}G3UOLv0dkJHTZxAwmhrIC2CRBZ4VJgTB

web_admin_enable   : true
web_admin_ssl      : true
web_admin_external : false
remote_cli_enable  : false
rest_admin_enable  : true
rest_admin_ssl     : true
...
Example: resinctl generate-password
unix> resinctl generate-password my-admin my-password
admin_user : my-admin
admin_password : {SSHA}G3UOLv0dkJHTZxAwmhrIC2CRBZ4VJgTB

admin_user

admin_user creates a login user name for /resin-admin administration, REST, and remote resinctl CLI administration. It is used with admin_password and web_admin_enable.

admin_password is generated with either the CLI resinctl generate-password or the /resin-admin login screen.

Example: admin_user in resin.properties
...
admin_user     : my-admin
admin_password : {SSHA}G3UOLv0dkJHTZxAwmhrIC2CRBZ4VJgTB

web_admin_enable   : true
web_admin_ssl      : true
web_admin_external : false
remote_cli_enable  : false
rest_admin_enable  : true
rest_admin_ssl     : true
...
Example: resinctl generate-password
unix> resinctl generate-password my-admin my-password
admin_user : my-admin
admin_password : {SSHA}G3UOLv0dkJHTZxAwmhrIC2CRBZ4VJgTB

app.http

The HTTP port for the 'app' cluster. The "app." is a prefix to the http property, restricting it to the named cluster, "app".

Example: app.http
...
app.http : 8080
...

app.https

The HTTPS port for the 'app' cluster. The "app." is a prefix to the https property, restricting it to the named cluster, "app".

app.https is generally used with openssl_file, openssl_key and openssl_password.

Example: app.https
...
app.https : 8443
...

cluster_system_key

cluster_system_key configures a shared secret across Resin servers in a cluster. The shared secret is checked when servers in the cluster connect. The key can be any string.

Example: cluster_system_key
cluster_system_key : ms8cntp8743z

dependency_check_interval

dependency_check_interval sets how often Resin will check for updated files. In development this will be a small value. In deployment it can be a larger value.

Example: dependency_check_interval
dependency_check_interval : 2m

elastic_cloud_enable

elastic_cloud_enable lets dynamic servers join a cluster. If the "start" command either has an "--elastic-server" flag or if the elastic_server property is set, Resin will connect to the cluster as a new dynamic server.

The cluster is either specified by "--cluster foo" or the home_cluster property. The cluster triad hub servers are specified by the app_servers property.

Example: elastic_cloud_enable
app_servers : 182.168.1.10:6800

elastic_server       : true
elastic_cloud_enable : true
home_cluster         : app

To start a dynamic server, use resinctl with start and specify --elastic-server to force a dynamic server. The --cluster is optional if a home-cluster has been defined.

Example: elastic_cloud_enable
# resinctl start --elastic-server --cluster app

elastic_dns

elastic_dns is used in cloud environments that assign IP addresses or DNS names after the server starts, for example in an EC2 environment. When elastic_dns is enabled, Resin will start the server, wait and retry until the local IP addresses or DNS resolve to a matching server.

For example, a Resin cluster might have a fixed pre-allocated DNS name of "app0.mydomain" and app_servers might include that address. At server boot time, the cloud assigns the dynamic IP 192.168.2.114. Later the cloud or the user will attach the IP to the DNS name "app0.mydomain". Resin will then recognize it and start with the correct value.

  1. Reserve DNS address "app0.mydomain" with cloud provider.
  2. Configure resin.properties with that fixed address and elastic_dns.
  3. Start Resin instance in the cloud (with address 192.168.2.114)
  4. [Resin is in wait mode until the following step because it doesn't lookup "app0.mydomain" to 192.168.2.114 in the configuration files.]
  5. Assign the DNS name "app0.mydomain" to 192.168.1.10 with the cloud provider.
  6. Resin will detect the new assignment and start as that server.
Example: elastic_dns
app_servers : app0.mydomain:6800

elastic_dns           : true

You can specify the elastic_dns in the resin.properties or equivalently specify it on the command line as --elastic-dns.

Example: CLI elastic-dns
# resinctl start-all --elastic-dns

elastic_server

elastic_server starts the server as a dynamic server and joins a cluster. The dynamic server must have a hub server configured in the cluster to register itself. The cluster must also have the elastic_cloud_enable set to enable dynamic servers.

When the "start" command either has an "--elastic-server" flag or if the elastic_server property is set, Resin will connect to the cluster as a new dynamic server.

The cluster is either specified by "--cluster foo" or the home_cluster property. The cluster triad hub servers are specified by the app_servers property.

  • Either elastic_server in the resin.properties or --elastic-server on the command line to start an elastic server.
  • Either home_server in the resin.properties or --cluster on the command line to specify the cluster.
  • elastic_cloud_enable in the resin.properties to enable dynamic servers.
  • At least one static server defined in app_servers in the resin.properties as the hub. Three servers is preferred.
Example: elastic_server
app_servers : 182.168.1.10:6800

elastic_server       : true
elastic_cloud_enable : true
home_cluster         : app

To start a dynamic server, use resinctl with start and specify --elastic-server or elastic_server in the resin.properties to force a dynamic server. The --cluster is optional if a home-cluster has been defined.

Example: elastic_server
# resinctl start --elastic-server --cluster app

email

email is an admin email address used to send automatic reports like weekly PDF reports.

Example: email
email : myuser@admin.example.org

http

The HTTP port for all servers, usually restricted to the cluster or server as app.http or web.http. If the plain http property is used, it is the default http for all servers.

Example: http
...
http     : 8080
app.http : 8081   # overrides for a server in cluster 'app'
...

http_address

http_address selects a specific IP address and port for HTTP. It can be useful when each server needs to bind to a different address.

The http_address can be qualified by the cluster or the individual server like other properties. For example, app-0.http_address configures the address for server app-0 in the app cluster.

Example: http_address
...
app-0.http_address     : 192.168.1.10
app-1.http_address     : 192.168.1.11

app.http               : 8080
...

http_ping_urls

http_ping_urls is a list of URLs to check for server reliability. Resin's health system will periodically check the URLs on the current server. If the server does not respond, the health system will force an automatic restart of Resin.

Example: http_ping_urls
http_ping_urls : http://www.myfoo.com/my-test http://www.mybar.com/my-test2

jvm_args

jvm_args defines the JDK memory and GC parameters to start the Resin process.

Example: jvm_args
jvm_args : -Xmx2G -XX:MaxPermSize=256m

openssl_file

openssl_file configures the OpenSSL *.crt certificate file when using SSL. The file location is relative to the resin.xml file.

Example: openssl_file
app.https         : 8443

openssl_file      : keys/foo.crt
openssl_key       : keys/foo.key
openssl_password  : my-password

openssl_key

openssl_key configures the OpenSSL *.key key file when using SSL. The file location is relative to the resin.xml file.

Example: openssl_key
app.https         : 8443

openssl_file      : keys/foo.crt
openssl_key       : keys/foo.key
openssl_password  : my-password

openssl_password

openssl_password configures the password for OpenSSL key file when using SSL.

Example: openssl_key
app.https         : 8443

openssl_file      : keys/foo.crt
openssl_key       : keys/foo.key
openssl_password  : my-password

port_thread_max

port_thread_max restricts the active threads available for a single port. Connections beyond the limit will use the async/select manager, and queue for an available thread.

port_thread_max can be used to limit the maximum load on an overloaded system. If more connection arrive than port_thread_max and beyond the select manager, they will be delayed instead of overloading the system.

Example: port_thread_max
...
port_thread_max   : 256
accept_thread_max : 32
accept_thread_min : 4

properties_import_url

properties_import_url adds a new properties file to be processed after the resin.properties. Cloud servers using EC2-style /user-data can use the url to customize properties for each server.

Example: properties_import_url for EC2
...
properties_import_url : http://169.254.169.254/latest/user-data

proxy_cache_enable

proxy_cache_enable enables Resin's HTTP proxy cache. The proxy cache improves performance by saving the server's generated pages. It can be used for formatted web pages or REST-style GET pages that change infrequently.

Example: proxy_cache_enable
proxy_cache_enable : true
proxy_cache_size  : 256m

proxy_cache_size

proxy_cache_size is the size of the in-memory proxy cache size. The actual maximum size is much larger, because the memory is used as a block cache for a disk based store. The memory block cache is also used for distributed caching.

Example: proxy_cache_size
proxy_cache_enable : true
proxy_cache_size  : 256m

remote_cli_enable

remote_cli_enable enables the CLI resinctl to be used for remote servers. By default the CLI is restricted to the local network.

Example: remote_cli_enable
remote_cli_enable : true

rest_admin_enable

rest_admin_enable enables REST-based administration of a Resin server. REST can be used to integrate Resin with remote administration consoles or status scripts.

rest_admin_enable requires an admin_user and admin_password for security. It can optionally be restricted to SSL ports with resin_admin_ssl.

Example: rest_admin_enable in resin.properties
...
rest_admin_enable  : true
rest_admin_ssl     : true

admin_user     : my-admin
admin_password : {SSHA}G3UOLv0dkJHTZxAwmhrIC2CRBZ4VJgTB
...

rest_admin_ssl

rest_admin_ssl requires an SSL connection for REST-based administration of a Resin server. REST can be used to integrate Resin with remote administration consoles or status scripts.

Example: rest_admin_ssl in resin.properties
...
rest_admin_enable  : true
rest_admin_ssl     : true

admin_user     : my-admin
admin_password : {SSHA}G3UOLv0dkJHTZxAwmhrIC2CRBZ4VJgTB
...

sendfile

sendfile enables operating system sendfile() call, which will send an entire file without requiring Resin to read the file itself. sendfile is particularly useful when much of the traffic is large static files.

Example: sendfile
...
sendfile   : true
tcp_cork   : true

session_store

session_store enables clustered persistent sessions for failover.

Example: session_store
...
session_store : true
...

setuid_user

On unix, setuid_user runs the Resin instance as the specified user for security.

Example: setuid_user
...
setuid_user : resin
setuid_group : resin
...

setuid_group

On unix, setuid_group runs the Resin instance as the specified group for security.

Example: setuid_group
...
setuid_user : resin
setuid_group : resin
...

tcp_cork

tcp_cork enables advanced TCP flow control on Linux systems for improved performance of large files. When it is enabled, sent data will be buffered in the operating system until the buffers fill, instead of being sent out with partial buffers. An application flush() will still force the data to be sent out.

Example: tcp_cork
...
tcp_cork   : true

web_admin_enable

web_admin_enable enables /resin-admin for a Resin server. /resin-admin can show the server status, report statistics graphs, deploy applications, and generate PDF reports.

web_admin_enable requires an admin_user and admin_password for security. It can optionally be restricted to SSL ports with web_admin_ssl.

Example: web_admin_enable in resin.properties
...
web_admin_enable  : true
web_admin_ssl     : true

admin_user     : my-admin
admin_password : {SSHA}G3UOLv0dkJHTZxAwmhrIC2CRBZ4VJgTB
...

web_admin_external

web_admin_external enables /resin-admin access for servers outside the local network. If enabled, it should be always used with web_admin_ssl.

Example: web_admin_external in resin.properties
...
web_admin_enable   : true
web_admin_external : true
web_admin_ssl      : true

admin_user     : my-admin
admin_password : {SSHA}G3UOLv0dkJHTZxAwmhrIC2CRBZ4VJgTB
...

web_admin_ssl

web_admin_ssl requires an SSL connection for /resin-admin administration of a Resin server. /resin-admin can show the server status, report statistics graphs, deploy applications, and generate PDF reports.

Example: web_admin_ssl in resin.properties
...
web_admin_enable  : true
web_admin_ssl     : true

admin_user     : my-admin
admin_password : {SSHA}G3UOLv0dkJHTZxAwmhrIC2CRBZ4VJgTB
...

webapp_multiversion_routing

webapp_multiversion_routing is a deployment versioning system where Resin selects the most recent deployed application. Web-apps named with numeric suffixes, e.g. foo-10.0.war and can be browsed as /foo. When a new version of the web-app is deployed, Resin continues to route active session requests to the previous web-app version while new sessions go to the new version, so users will not be aware of the application upgrade.

Example: webapp_multiversion_routing
...
webapp_multiversion_routing : true
...

Copyright © 1998-2015 Caucho Technology, Inc. All rights reserved. Resin ® is a registered trademark. Quercustm, and Hessiantm are trademarks of Caucho Technology.