This is a manual for administering all the different aspects of the Locomotive Application Server. If you are a System Administrator or DBA (Database Administrator) who is in charge of making sure that everything runs smoothly on your web site or database server, then this book is for you. This book does not teach you how to program for the Locomotive, nor does it teach you how to install the Locomotive; those books are "The Locomotive Developer's Guide" and "How to Install the Locomotive", respectively.

This administration manual assumes that you have already installed the Locomotive on your system, and that you are aware of the different components that need to be installed. It also assumes that you are very familiar with your own operating system (UNIX or NT), with the database you're using, with your web server, and with running Java programs on your system.

This manual is designed as a reference that helps you pinpoint problems you might have and explains the routine tasks you need to do to keep your Locomotive running smoothly. This manual is laid out in the following sections:

1. First, we give an overview of what the Locomotive is, and where it fits on a web site.
2. Next, we talk about how to start and stop a Locomotive. Here, we go into more detail than in the Installation Guide.
3. Then, we talk about each of the different config files, and what each config does.
4. Then, we talk about a Perl script called watchloco that you can customize to monitor your Locomotive-powered web site.
5. After that, we talk about some routine tasks involved in maintaining your Locomotive-powered web site, including archiving log files and generating statistics.
6. Finally, we talk about some troubleshooting tools, and explain the meaning of various error web pages.
7. In Appendix A, we talk about what you can do if you Locomotive stops responding.
8. In Appendix B, we discuss a typical setup which allows the programmers to write code for the Locomotive while the graphics and HTML designers create the HTML templates, all at the same time.
9. In Appendix C, we discuss how you can set up a separate staging area and a production or "live" site, and how you might "go live".

Table of Contents

Appendix C. Publishing the Staging Site to the Live Site.

The Locomotive is a server program. It listens on a TCP port for requests from clients. Once it starts running, it can handle requests forever, until you explicitly shut it down. You can run several Locomotive servers on your machine at once, to improve parallelization.

The Locomotive is not part of the web server, nor does it require the web server to be running. In order for a web server to communicate with the Locomotive, a special piece of software called a tunnel is used. It can be either a CGI or a library that is linked into the web server via its native API (examples include Netscape's NSAPI, the Apache API, or Microsoft's ISAPI). We currently provide a CGI program called locolink and NSAPI for Solaris, and we are working on other tunnel alternatives. "locolink" is an abbreviation for "link to the Locomotive" application server.

You can run as many Locomotives on your system as you would like, on as many separate machines as you like, so that your web site can scale up to an unlimited amount of web traffic. You can set up your system with as many machines as you would like. You can put your web server(s) on any machine(s), your database server(s) on any machine(s), and your Locomotive(s) on any machine(s). If your entire web site is behind a firewall, you can set up an HTTP proxy or filter on your firewall machine to forward HTTP requests to your web server inside the firewall. This will allow anyone in the world to access your web site, while preventing people from having unauthorized access to your Locomotive servers or your database.

Here are the utilities included in the bin/ directory:

This script calls the java command that gets the Locomotive up and running. It requires the shell environmental variable LOCO_HOME to be set to the directory where your Locomotive is installed. When you run the script, you can specify the location of the loco.conf file to use as an argument. If you don't, the script will try to start a locomotive using a config file located at $LOCO_HOME/config/loco.conf.

This is a program that tells the Locomotive to finish handling any requests, close its database connections, and die. You can specify the port number and IP address of the Locomotive to stop, using -p <port number> and -a <address>; the defaults are port 5421 and localhost, 127.0.0.1.

Note that there is special security protection in the Locomotive which prevents people from being able to run stoploco on their own machine to shut down a Locomotive on your web site. The Locomotive will listen to a stoploco and shut down ONLY if that stoploco program was run from an accepted IP address. The Locomotive has two configuration variables in loco.conf which specify an IP address and a mask, much like the IP address subnet feature of many web servers. For example, if we have the following in loco.conf:

    LOCO_ACCEPT_IP                      127.0.0.1,225.16.0.9
    LOCO_ACCEPT_SUBNET                  255.255.255.255,255.255.255.0

This script simply runs the stoploco and startloco scripts in order. It accepts a combination of the command line parameters of the other two scripts. Here's the usage:

restartloco [-p port] [-a ip address] [-f config-file]

If you are running multiple Locomotives, you could create your own scripts, using our utilities, for starting or stopping each particular Locomotive -- for example, startloco1, startloco2, etc. Alternatively, in Unix, you can create multiple aliases for running a script with different sets of arguments, for example:

alias start1 startloco /usr/local/locomotive/config/loco_p5421.conf
alias start2 startloco /usr/local/locomotive/config/loco_p5422.conf

Once you start running a Locomotive, there is very little you need to do to keep it running smoothly. Really, the only major thing you need to do is to make sure that you don't run out of disk space. Your web server and the Locomotive both generate plenty of log files, and your database probably regularly needs more space. You must regularly back up your log files onto other disks or onto tape drives, and then remove these files, otherwise you will run out of space. If you are running multiple Locomotives, be sure to back up the Event Log and the Server Log for all Locomotives. Remember that a Locomotive automatically creates a new Server Log and a new Event Log at midnight each night, because both log files have a date prefix which tells exactly what day they were created.

If you would like the ability to start or stop your Locomotives remotely, from any Web browser, remember that you can include our utilities in your web server's CGI directory, so that you can run them as CGI programs. Or, you can create your own scripts which use these utilities, and run your scripts as CGI programs. You might consider putting these CGI programs into a password-protected directory in your web server's document root directory, for more security.

If you do set up these CGI programs, there is another potential benefit. Remember that there is a script in bin/ called watchloco which watches over your Locomotives (see below). It's possible to modify watchloco so that it can detect whether a particular Locomotive is responding or not, and then, if it is not responding, watchloco can restart it. To do this, you need to know Perl. If you set up watchloco this way, then it could save you some stress and some irritated users, because watchloco can respond quickly to unresponsive Locomotives.

For stopping a Locomotive, there are also two other alternative ways.

You can login to your Locomotive system as a super user (see "Creating a Locomotive Super user" in the Installation Guide) and use the ServerHandler URL command:

.../locolink/srv?shutdown

If a Locomotive is not responding to anything you do, whether you use stoploco or the srv?shutdown URL, then you will have to login to the machine that's running it, and stop it just as you would stop any other process on that machine. When this happens, try referring to Appendix A, "Forcing the Locomotive to Stop". Keep in mind that if you have more than one Locomotive running on your machine, you should make sure to stop the right one. Please note! We do not recommend this as a standard way of stopping Locomotives. It is better to shut down a Locomotive gracefully using stoploco or srv?shutdown, because those allow the Locomotive to finish handling web requests from users.

The Locomotive is a highly configurable application that can be altered to fit many different situations and needs. Configuring the Locomotive consists in editing the two required Locomotive config files, usually called loco.conf and hrt.conf. The loco.conf file holds general Locomotive configurations, while the hrt.conf file controls how URLs coming into the Locomotive are mapped to individual handlers. This guide will attempt to explain each.

Setting up the loco.conf file

1. Introduction
2. Each of the config options explained
3. Troubleshooting loco.conf settings

Setting up the hrt.conf file

1. Introduction
2. Setting up the included handlers
3. Troubleshooting hrt.conf settings

Setting up the loco.conf File

The loco.conf file holds all the general Locomotive configurations. Many of these configurations are essential to the Locomotive, and must be correctly set up before the Locomotive is started up. Many of the errors you may see while operating the Locomotive can be traced back to incorrect settings here.

You may comment lines in the config files by placing a '#' before the text you'd like to be ignored when the file is read by the Locomotive.

Any configurations which are not entered in the loco.conf file are automatically set to the default values, which are listed below. The sample loco.conf file that comes with the Locomotive distribution also contains all the default values.

These variables may be accessed by any Handler operating within the Locomotive. The Developer's Guide explains how you can do this.

System Identifications

• SYSTEM_TAG  The entire Locomotive system's identity tag. See below.
  Default value: COMPANY_X

• SYSTEM_INSTANCE_ID  The identity tag of the particular Locomotive application server this config is used for. In a system with multiple application servers, all servers should have the same SYSTEM_TAG, but each should have its own SYSTEM_INSTANCE_ID.
  Default value: sv_one

• LOCO_INST_ID  A numerical identifier distinguishing this application server from all others that have the same SYSTEM_TAG. The identifier must be an integer greater than 0 (that is, 1, 2, 3, ...), and it must be unique within the pool of servers. This is used to facilitate virtual sessions. IMPORTANT: If multiple servers in a pool have the same LOCO_INST_ID, their performance will suffer. Currently there is no restriction that the servers be numbered continuously starting with 1, but this is recommended for forward compatibility.
  Default value: 1

• LOCO_URL_MAIN  The Base URL this Locomotive is handling requests for. This is not used for anything except for self-referral in the administration handler.
  Default value: http://localhost.localdomain/cgi-bin/locolink

• LOCO_URL_HOMEPAGE  The url pointing to the default handler. Again, not used for anything except as an identification.
  Default value: base

• NSAPI_TUNNEL_URI_TOKEN_PREFIX  This is significant only when using the NSAPI tunnel. It denotes the URL token used by the web server to identify and send requests to the NSAPI module. For example, if the url is http://www.locomotive.org/foo/ll_test/bar/mymodule?arg1+arg2, the url_tokens will start with 'bar' and the locomotive will look for a module called 'bar' in Handler Routing Table. If the web server simply defaults to using the NSAPI module shared object, then you can set this to some random no-spaced string like /dfa3s. See the NSAPI Tunnel Documentation for more information.
  Default value: /ll_

Directory Information

• SYSTEM_SERVER_ROOT_PATH  An absolute path the base directory for the Locomotive.
  Default value: /usr/local/loco

• LOCO_TEMPLATE_ROOT_PATH  The path, relative to SYSTEM_SERVER_ROOT_PATH, to the base template directory.
  Default value: templates

• LOCO_UPLOAD_PATH  The path, relative to SYSTEM_SERVER_ROOT_PATH, directory where files uploaded from forms should be stored.
  Default value: upload
• SERVICE_CLASSPATH  The directory, relative to SYSTEM_SERVER_ROOT_PATH, where service (Handler and Servlet) classes are to be located, if you want to reload them. Make sure that this directory is not in your CLASSPATH, or else you won't be able to reload the classes!
  Default value: servlet

Network Information

• LOCO_PORT  The TCP Port this Locomotive is listening on. UNIX users- check your /etc/services file to make sure this does not conflict with other services.
  Default value: 5421

• LOCO_PORT_BACKLOG  How many requests the port should allow to wait for servicing at one time. If the load on your server is high and your requests are taking a fairly long time to handle, you may want to set this to a higher value.
  Default value: 16

• SMTP_SERVER_NAME  The name of the mail server for the Locomotive to send mail through. Note that the current version of the Locomotive does not spool messages when the mail server is down. Any messages send while the mail server is down will be lost.
  Default value: localhost

• SMTP_SERVER_PORT  The port the mail server is listening on.
  Default value: 25

• SMTP_SERVER_TIMEOUT  The number of seconds before the mail server connection is timed out.
  Default value: 60

• NORMAL_FORM_CONTENT_LENGTH  The longest form length accepted for a normal form, in bytes.
  Default value: 131072

• MULTIPART_FORM_CONTENT_LENGTH  The longest length in bytes accepted for a multipart form, which contains a file upload. Note that reading in large upload files is dependent on the user's bandwidth, and because the locolink tunnel waits only 60 seconds for a response before terminating the connection, a file close to default limit of 10 MB may result in an error on a slow connection.
  Default value: 10485760

• LOCO_ACCEPT_IP  In order for this Locomotive to listen to a request from a stoploco program, the stoploco program must originate from an accepted IP address. This should contain a list of accepted IP addresses, separated by commas. It can be modified by LOCO_ACCEPT_SUBNET to allow a range of IP's. For example, 127.0.0.1,172.16.0.0 would allow connections from the localhost and from 172.160.0.0
  Default value: 127.0.0.1

• LOCO_ACCEPT_SUBNET  A comma delimited list of subnets to modify the LOCO_ACCEPT_IP values. For instance, if we have the LOCO_IP_ACCEPT values to those set in the example above, and we have a LOCO_IP_SUBNET of 255.255.255.255,255.255.255.0, then we allow requests from the localhost and from 172.160.0.*, where * is any number from 0-255.
  Default value: 255.255.255.255

Service Information

• SERVICE_DEFAULT  This should be set to which service type you'd like requests which do not specify a service to use. Currently, you can either set this to HANDLER or SERVLET.
  Default value: HANDLER

• HANDLER_ROUTING_TABLE_PATH  The path, relative to SYSTEM_SERVER_ROOT_PATH, to the hrt.conf file used with this Locomotive. For more information on the Handler Routing table, see below.
  Default value: config/hrt.conf

• HANDLER_URI_TOKEN_PREFIX  All Requests which point to Handlers will have to have this at the beginning of their request URI. So, for instance, if you set this to 'handler', then all handler requests will need to have a URL like:
  www.somewhere.com/locolink/handler/yourhandler?tokens
  Default value: handler

• SERVLET_ROUTING_TABLE_PATH  The path, relative to SYSTEM_SERVER_ROOT_PATH, to the servlet.conf file used with this Locomotive. To learn more about the servlet routing table, see below.
  Default value: config/servlet.conf

• SERVLET_URI_TOKEN_PREFIX  All Requests which point to Servlets will have to have this at the beginning of their request URI. So, for instance, if you set this to 'servlet, then all servlet requests will need to have a URL like:
  www.somewhere.com/locolink/servlet/yourservlet/
  Default value: servlet

Session and Cookie Configurations

• LOCO_COOKIE_DOMAIN_MAIN  The domain to return cookies to. This should be the name of the domain that the locomotive sits behind. It's easiest to make this your top level domain, by making it '.yourdomain.com'. You can also set it to a specific host by leaving out the leading '.'- 'somemachine.yourdomain.com'. For more information, see Netscape's cookie documentation.
  Default value: .locomotive.org

• LOCO_SESSION_EXPIRE_TIME  The number of seconds required between visits to the site before the user's session, and all authentifications based on it, are wiped.
  Default value: 3600

• LOCO_SESSION_AUTOHANDLE  Whether the Locomotive should handle expired sessions. If YES, when a session expiration is detected, the locomotive will return the LOCO_TEMPLATE_ROOT_PATH/error/session_expired.tmpl template, which contains a message telling the user to log in again. If NO, then session expiration handling is left up to the individual handlers.
  Default value: YES

• PERSISTENT_SESSION_COOKIE  Whether the session cookie, and all authorizations tied to it, should remain across browser uses. If YES, then the cookie is written into the cookies file in the user's browser. If NO, then the cookie will vanish when user quits the browser. Persistent cookies are recommended against, because they expose the users to potential security violations by other people who make use the same computer or browser.
  Default value: NO

• BSTAMP_COOKIE  Whether a Browser stamp cookie should be sent to users. While the session cookie will change with each new session, the BStamp is a persistent cookie which can be used to track an individual browser's access to the site. Note that this does not necessarily correlate to an individual user's access to the site- See the description above. We recommend setting this value to YES and the above value to NO, for the security reasons mentioned above.
  Default value: YES

Database Configurations

• DB_AUTOCONNECT  Whether to set up the database connection pool at startup. If set to NO, then there will be no access to session or user information until RequestManager.createDBConnectionPool is called.
  Default value: YES

• DB_TYPE  The type of database used to handle the Handle the internal Locomotive functions, such as sessions and user management. Currently, Oracle, Informix, Solid, Cloudscape, and MySQL are supported.
  Default value: Oracle

• DB_DRIVER_CLASSNAME  The class name of the JDBC driver used to connect to the database. See the JDBC home page or our installation guide for more information on using JDBC.
  Default value: weblogic.jdbc.oci.Driver

• DB_CONNPOOL_URL  The URL used by the driver to connect to the database. See the links above for more information
  Default value: jdbc:weblogic:oracle

• DB_CONNPOOL_USERNAME  The database username to use for connecting to the database. We recommend creating a Loco user in the database. See the Database setup documentation for more information.
  Default value: loco_user

• DB_CONNPOOL_PASSWORD  The database user's password. See above.
  Default value: loco_user_pw

• DB_CONNPOOL_MAX_CONNECTIONS  The maximum number of database connections to have open at any one time. This number will likely depend on your specific database license. This number should be only slightly smaller than the LOCO_MAX_POOLED_THREADS value, as Requests waiting for database access will simply block until a connection becomes available.
  Default value: 10

• DB_CONNPOOL_MIN_CONNECTIONS  The minimum number of database connections to have open at any one time. This number should be analogous to LOCO_MIN_POOLED_THREADS, as Requests waiting for database access will block until a new connection can be created.
  Default value: 2

Logging Settings

• LOG_LEVEL  The level of verbosity for the primary Locomotive server log. Larger numbers provide more information. 0 is equivalent to org.locomotive.erver.Log constant LOG_LEVEL_NO_LOGGING, while 9 is equivalent to LOG_LEVEL_REALLY_VERBOSE. The higher levels print more internal locomotive debugging information, which may be useful while developing, but might get in the way when in production. See the Log javadoc for more information. To learn how to write to the server log, see the Developer's Guide.
  Default value: 9

• LOG_PATH  The path, relative to the LOCO_SERVER_ROOT, where the main Locomotive server log is to be written. If the character '%' is found within the path, then it will be replaced with the current date, in the YYYYMMDD format, and log files will be automatically rolled over when each new day starts.
  Default value: logs/loco1-%.log

• EVENT_LOG_LEVEL  The verbosity level for the Event log. Goes by the same rules as the LOG_LEVEL config above. See the the Developer's Guide to learn how to record events in the event log.
  Default value: 5

• EVENT_LOG_PATH  The path, relative to the LOCO_SEVER_ROOT, where the Locomotive event log is to be written. Follows the same rules as the LOG_PATH above.
  Default value: logs/events1-%.log

Performance Related Settings

• LOCO_MAX_POOLED_THREADS  The maximum number of request threads running at any time. This value should be slightly larger than the DB_CONNPOOL_MAX_CONNECTIONS value.
  Default value: 20

• LOCO_MIN_POOLED_THREADS  The minimum number of threads used to handle requests. Must be at least one.
  Default value: 2

• LOCO_CHECK_NEW_TEMPLATE_FREQ  The number of requests to evaluate a template before the template is checked to see if it has been modified and reloaded if necessary. Recommended values are between 1, which checks every time, and 20. The higher the number the better the performance of template evaluation.
  Default value: 1
• USE_CACHED_SESSION_OBJECTS   The Locomotive allows you to store objects with sessions in handlers or servlets. These objects are kept in a cache, and are written to the database only upon server shutdown. While this is much faster, if you are running multiple servers and need to have your session objects available to each server, this won't do. If you want to bypass the cache and read and write from the database for each request, set this to FALSE. Otherwise, set it to TRUE
  Default value: TRUE

• AUTO_RELOAD_SERVICES   If your service classes are located in the SERVICE_CLASSPATH, they can either be reloaded automatically, whenever the class is recompiled, or manually, via the ServerServlet or ServerHandler. The manual setting is faster; the automatic setting makes development a lot easier, by reloading the class the first time you request it after you've compiled it.
  Default value: TRUE

TroubleShooting loco.conf Settings

The first thing to do whenever you encounter any problems is to look in the Locomotive server log. This keeps track of any Exceptions that are thrown by handlers, as well as any problems which occur inside the Locomotive. If the log level is set to a high number, you'll also find a bunch of request specific information- everything from the requester's referrer IP to his or her browser type. Often these can be helpful in debugging odd or inconsistent problems. Here's a list of common problems and possible solutions that may be helpful:

 

Database Connection Pool will not initialize

Configs Involved: DB_TYPE, DB_DRIVER_CLASSNAME, DB_CONNPOOL_URL, DB_CONNPOOL_USERNAME, DB_CONNPOOL_PASSWORD

There are a number of reasons why the DB Connection Pool might not start. First, check with your JDBC driver documentation to make sure you have the driver classname and the connection url correct. Next, make sure you have the correct username and password. If you're sure all this is correct, then look in the server log for hints at what the error is. It could be your driver has bugs- see the List of JDBC drivers we recommend and make sure your driver is part of the list.

Locomotive starts without problems, but does not seem to be receiving any connections.

Configs Involved:LOCO_PORT

Make sure your LOCO_PORT config is set to the same port the tunnel is sending information to. The default port is 5421; this is the same port that the compiled locolink CGI sends to. If you need to change this, you need to recompile the CGI. The Installation Guide explains how to do this. The port the NSAPI and Apache tunnels send to is much more easily configured: just alter the tunnel locations config file to set the port to be the same as that in the loco.conf file. See Tunnel Documentation for more information.

Locomotive does not seem to be allowing persistent sessions

Configs Involved:LOCO_COOKIE_DOMAIN_MAIN, DB_AUTOCONNECT

There are two reasons why this might happen. First, make sure the Locomotive is connected to the database it uses for user and session management. The connection is usually performed automatically; however, if you set the DB_AUTOCONNECT config to false, you have start it up in a handler with the Loco.createDBConnectionPool() method. If you're sure the database connection pool is being created at startup, then the problem might be that the Locomotive isn't getting it's session cookies correctly. If your LOCO_COOKIE_DOMAIN_MAIN config is not set correctly, then the Locomotive won't know which cookies to request from the web server for each request. Though the session cookies get sent, they never get received when the next request comes. To check to see if this is the case, set the LOG_LEVEL to 9 and look at the cookies that come in for each request- they'll be listed on a line beginning with HTTP_COOKIE. If you don't see any cookies whose names begin with LOCOSID, then it's probably the LOCO_COOKIE_DOMAIN_MAIN variable.

Setting up the hrt.conf and servlet.conf Files

The Locomotive maps requests to module classes based on what url tokens it finds in each request. The hrt.conf and servlet.conf files hold these mappings for their respective services. The format of each file is the same- below we'll describe the hrt.conf, but you can assume that what we say here goes for the servlet.conf file, too.

The first word of any line in the hrt.conf file is assumed to be the url token; the second is the class to map it to. So,

base org.locomotive.module.base.BaseHandler

http://www.someplace.com/locolink/base?login

All the classes in the hrt.conf file must implement the handler interface- if they don't, then the Locomotive will issue an error upon startup. This error will be recorded in the server log file; if you don't see your handler appearing after the Locomotive starts, check the log file to make sure nothing went wrong.

You can also specify a Properties file for each handler to be loaded by the Locomotive on startup- just put the absolute path to the file, in quotes, after the class name. For instance, the default mapping for the PublisherHandler looks like: pub org.locomotive.module.pub.PublisherHandler "/usr/local/locomotive/pub.properties"

If you specify a properties file, then it will be accessible to your Handler via the handler_config field in HandlerData. If the properties file doesn't exist or can't be read, then the Locomotive will log the error and will refuse to start up. Servlet's also specify their config files this way in the servlet.conf file. Servlets have a built in method called servlet.getServletConfig() that will return the properties object loaded from this file. For more information on Properties and how to use them, see the Sun javadoc for it.

Anything else in the hrt.conf file besides the url token-class mappings should be put in comments. Comments, for this file, look like '//'. The hrt.conf file included with the locomotive has a ton of comments, so this should be clear if you've looked in there before.

Some url tokens are already taken by internal Locomotive handlers. These are:

     srv                  org.locomotive.loco.ServerHandler
     default              org.locomotive.loco.DefaultHandler
     unknown              org.locomotive.loco.UnknownHandler

'srv' is the only token that can't be overriden. It always maps to the ServerHandler, which allows administrators to view Locomotive configuration settings, flush cached templates, and shut down locomotives. The other two map to simple default handlers, and can be overriden if you choose to do so.

TroubleShooting hrt.conf Settings

You've entered the class in the hrt.conf, but it doesn't seem to be handling requests for the URL you've mapped it to.

• In your handler's init method, place a log statement that records that the handler has been loaded. Now, when you restart the Locomotive, if you see the logging statement, you know the handler was loaded.
• If you're handler doesn't load, then make sure you've entered the entire class name, including the package names, for the class.
• If you know the handler has been loaded, make sure the url you're requesting is exactly the same as the token in the file. Keep in mind that the url tokens are case sensitive.

When you're curious about how a Locomotive is performing, or when you're trying to debug a problem, sometimes it might help you to get some information about a Locomotive Server while it's running. The Locomotive comes with a fairly basic administrative interface called the ServerHandler. There's an analogous ServerServlet for those who prefer; it does the same thing and uses the same urls as the ServerHandler.

To access the ServerHandler, you have to login as a user who has certain loco flags set. The Admin user that is installed automatically has all the necessary flags, so you may want to log in as that user to user the ServerHandler. Otherwise, you can set your user's flags manually in the database by setting the LOCO_FLAGS column in the LOCO_USERS table. Here's the values for each flag:

0              LOCO_FLAGS_DEFAULT
1              LOCO_FLAGS_CAN_VIEW_SERVER_STATUS
2              LOCO_FLAGS_CAN_CHANGE_LOCO_VARS
4              LOCO_FLAGS_CAN_SHUT_DOWN_LOCO

Try logging in as an admin user and connecting to your Locomotive using the following url:

.../locolink/srv?status

You should see a page listing all the configuration variables and internal status variables for a Locomotive. (If your locolink routes to multiple Locomotives, this page will represent only the data for one Locomotive, which is chosen at random. You can tell which Locomotive you're currently looking at by checking the SYSTEM_INSTANCE_TAG variable, which should be set differently for each Locomotive you're running).
Here are explanations for some of the more salient status fields:

Currently Active Threads 4

The number of threads that are running in the Locomotive is important because it tells you whether this Locomotive is reaching its capacity. If you are consistently seeing a high number of threads, for example, more than 20, then you should probably start another Locomotive running, either on the same machine or on another machine, in order to improve performance.

Open DB Connections 4

The number of database Connections that are open may be important to you if you have many Locomotives running on the same machine. Some databases put a limit on the number of database connections that clients can open into their servers. Check your database administration guide to make sure that you're not exceeding this limit.

Free Java Heap Memory 406360

Knowing how much free memory you have can help you debug when you have a potential memory leak. Also, it could tell you whether you need to allocate more memory to this Java process.

SYSTEM_SERVER_ROOT_PATH /home/loco

Knowing the Locomotive's root directory is very important, of course. Knowing this will tell you where the config files and the log files for this Locomotive are located.

LOCO_PORT 5425

Since you can run only one Locomotive on a TCP port, knowing the port for this Locomotive is a quick way to identify which Locomotive you're looking at.

By the way, you can also find out all the values of the configuration variables (the ones with ALL CAPITAL LETTERS) just by looking at the loco.conf file for this Locomotive. The reason why they are also displayed on the /srv?status page is purely as a convenience, so that you can see the values of the configuration variables from any Web browser.

The ServerHandler also let's you perform some basic administration cleanup functions.

Reload Status

When you click on this URL, the page will refresh itself with the latest information about the server. Click on it a few times to see how the data changes.

Reload Templates

Clicking on this URL will cause the Locomotive to flush its template cache and reload all the templates. If you have the config LOCO_CHECK_NEW_TEMPLATE_FREQ set to a very high number and you've recently edited your templates and want the changes to be displayed, this will do it for you.

Reload HandlerRoutingTable

This link appears for the ServerHandler. For the ServerServlet, the Reload ServletRoutingTable link appears. When this is clicked, the Locomotive will go back to the hrt.conf (or servlet.conf) file and reload all the entries it finds there. It will then shut down all the modules currently running, and re-initialize all the one's it found in the files. It will also reload all the Properties files it finds. If you need to switch which modules get routed to which URLs, or if you want to take a module down or put up a new module without shutting down the Locomotive, you can use this link.

Reload DBConnectionPool

The Locomotive keeps a pool of Database connections in a pool for availability. While this makes things more effecient, it doesn't allow for cleanup, which means that connections which become corrupted will get returned to the pool and re-used. If you begin to have strange SQLExceptions pop up in your server logs, you can try flushing out the old Database Connections and replacing them with new ones. Pressing this link will do that for you.

While we have tried to make the Locomotive impervious to problems, it is a complex piece of software, which uses a complex programming language, interacting with a web server and a database, which are also complex. So, there will sometimes be problems in this whole system. When problems arise, how can you make sure that you know about them as soon as possible, so you can fix them?

We've provided a Perl script called watchloco which can constantly monitor your web server and the Locomotive. You can set up watchloco, or "the watcher", as a "cron" job, so that it wakes up every few minutes and tries to access a Web page on your site that must be handled by a Locomotive. If the Locomotive responds in a reasonable time period, then the watcher finishes, taking no action. However, if the Locomotive does not respond, or is too slow, then the watcher will send an email alert to you. After you receive that alert, you can then take the necessary steps to fix the web server, the database, or the Locomotive.

The watchloco script is provided only as an example of a way to monitor the Locomotive system. If you wish to use it, you must modify it so that it will monitor your own web site, and send an alert message to your email address. You can also modify the script so that it monitors several Locomotives at once. However, Leverage does not provide technical support for the watchloco script; it is provided purely as an example of a utility. In the future, we are planning to develop a Locomotive monitoring system with more powerful features.

You might also be interested in gathering statistics on the usage of the Locomotive. We provide a Perl script called parse_events.pl which generates summary statistics about the usage of your site, by using the information in the Locomotive's Event Log files. This script is designed to be run every day. On Unix systems, you can use the "cron" command to run this command just before midnight (say, at 11:55 PM) every night. Here's an example of the cron entry for this script:

# generate statistics about the usage of the site each day
# at 11:55 p.m. and mail them to myself
#
55 23 * * * /usr/local/locomotive/bin/parse_events.pl < /usr/local/locomotive/logs/events*.log | mail ben@leverage.com

SESSIONS AND USER SUMMARY
13212 unique users 6934 total sessions 2313 authenticated sessions 4621 anonymous only sessions 164565 total impressions ...

The Locomotive Server Log is a good place to get information about each individual Web request that comes in. Here's an example of a chunk of the Server Log, with an explanation afterwards:

1998-07-16 13:39:55 PDT LOCO - dispatch REQ(3218) active: 4 out of 8
1998-07-16 13:39:55 PDT PT(4): firing
1998-07-16 13:39:55 PDT REQ(3218) reading envars...
...
1998-07-16 13:39:55 PDT REQ(3218) HTTP_USER_AGENT: Mozilla/4.05 (Win95; I)
...
1998-07-16 13:39:56 PDT REQ(3218) url tokens (3): base login

Notice that the date and the time come first on every line in the Server Log. In the first line from this example, the Locomotive is allocating a thread to handle this Web request. It tells us that the thread is "4 out of 8", which means that there are already 3 other threads that are handling other Web requests, and that this Locomotive has pre-allocated 8 threads for handling Web requests. So, we now know that there are 4 other threads that are free in this Locomotive. (The Locomotive pre-allocates threads and puts them into a "Thread Pool", because creating threads every time causes a large execution time overhead)

Most of the other lines in the Server Log are pretty self-explanatory. Notice that the Server Log tracks information about the kind of browser that the user is using, on the line with "HTTP_USER_AGENT". When you're trying to debug a feature on your Locomotive, it might help you to know what kind of browser caused the bug; sometimes, the browser itself is the problem.

Also, notice that the "URL tokens" for the Web request is also written into the log -- in this case, "base login". Knowing what the URL was is particularly helpful when trying to debug a single Web request.

Finally, notice that the Locomotive assigns a "Request ID" to every new Web request it receives. You can find that Request ID in the "REQ (3218)" part of the line. This Request ID is also recorded in the Locomotive's Event Log, so it can help you correlate the two logs very easily, which can help you debug a problem.

When installing or running the Locomotive, you may see one of the following error Web pages. We'll explain what each one means, and what you can do to fix the problem.

 

File Not Found The requested URL /cgi-bin/locolink was not found on this server.

 

 

Request Failed at LOCOLink: connect_failed: Connection refused

 

1. The Locomotive that you're trying to connect to is "dead"; its Java process has finished executing. You will need to start a new Locomotive. If you can't determine which Locomotive has died, then you should probably set up multiple locolinks, each one of which routes exclusively to a single Locomotive on your system, so that you can determine by process of elimination which Locomotive has died.
2. You may have set up your tunnel program incorrectly, so that it could not reach the Locomotive(s) that you wanted it to reach. Double-check that you configured your locolink CGI or other tunnel program with the right port number(s) and IP address(es) of your Locomotive(s), and check that you've compiled your tunnel program and put it in the correct directory.

 

Internal Server Error The server encountered an internal error or misconfiguration and was unable to complete your request.  Please contact the server administrator, webmaster@yourcompany.com and inform them of the time the error occurred, and anything you might have done that may have caused the error.

 

 

Login or Registration Not Available It appears that your browser does not support cookies. In order to register or log into this site you'll need to use a browser that supports cookies. If you think your browser does, you may simply be able to reload this page. If not, please enable cookies on your browser or come back with an appropriate browser.

 

 

There has been a LOCO Error Errormsg: There was a Locomotive error, code: login_lue.  RequestID: 114604 System Tag: LEVERAGE_DEV InstanceID: sv_one Date: Jul 09, 1998 11:47 AM Please mail a copy of this page to our site administrator, ben@leverage.com.

 

 

A module to handle the requested option cannot be found. This is probably due to a broken link in the referring document. Contact the server administrator.

 

You might also receive this page when you're trying to use the ServerHandler, and you are not logged in as a Locomotive Super user. In other words, we don't want ordinary users to know that the ServerHandler even exists, unless they have the right privileges. If they do try to use ServerHandler features, the Locomotive responds by saying, "what are you talking about?".

If a Locomotive is "frozen" -- if it's not responding when you try to access it using locolink or stoploco -- you will have to login to the actual machine that's running that Locomotive to stop it. Please note! We do not recommend this as a standard way of stopping Locomotives. It is better to shut down a Locomotive gracefully using stoploco or srv?shutdown, because those allow the Locomotive to finish handling web requests from users and shut down each module to save any caches and and clean up resources. On Unix, to stop a process, you would use the "kill" command. We recommend that you first kill the Locomotive's process ID with a QUIT signal, and then with a TERM or ABORT signal, because kill -QUIT forces the Java VM to print a "stack dump", or a stack trace for every thread, to an error file:

% kill -QUIT 2924; sleep 5; kill -TERM 2924

Where would you find the error file that contains the stack dump? Well, if you used startloco to start your Locomotive, startloco automatically creates an error file called loco_err-YYYYMMDD.HHMMSS in the same directory as that Locomotive's loco.conf file, where YYYYMMDD.HHMMSS is substituted with the exact date and time when that Locomotive was started. This error file captures all output from the standard error stream of the Java VM running that Locomotive.

By the way, notice that we knew the process ID of the Java VM running the Locomotive when we issued the "kill" command. (In this case, the process ID was 2924.) If you're running multiple Locomotives on one machine, it may not be very easy to figure out which Locomotive has which process ID. Here's a little trick that might help you. On Unix systems, the "ps" command can display information about all the processes running on a machine. For example, if we're using the Berkeley UNIX 'ps' that comes with most free UNIX flavors, we can use the following command:

% ps -auxwww | grep java

This will display all the processes whose command names contain the word "java". (note that the arguments to "ps" differ greatly from one operating system to another. Please consult your system's manuals.) Then, you might see a listing like this:

user1     16920   0.0   3.7 6848 4632 Jul 08   0:53 /usr/local/java/bin/java org.locomotive.loco.LOCO -f /home/loco/config/loco1.conf
user2     23042   0.0   3.1 6724 3932 Jul 10   0:24 /usr/local/java/bin/java org.locomotive.loco.LOCO -f /home/loco/config/loco2.conf

Notice that in this "wide" format, we can even see which loco.conf file is being used by each Locomotive process. We can use this information to identify the process ID of the Locomotive we're interested in. For example, Locomotive #1, using loco1.conf as its configuration file, has process ID 16920 (that's the first number on the line after the username "user1"), while Locomotive #2 has process IP 23042.

In this chapter, we'll talk about how to set up your "staging" web site. We're not going to go into detail about setting up individual Locomotive servers here; hopefully, you learned how to do that from the installation guide. Rather, we're going to talk at a more conceptual level.

When you setup your staging web site, you will need to devote at least one web server, one Locomotive, and one database to that system. That is because you need to have a site that is not public; no one should be able to access the staging site's web server. If there are multiple developers working on different features, then each of these developers might run their own Locomotive server for testing purposes. They can all share the same web server and the same database. You also need a database that is separate from your live site's database, because you don't want to accidentally modify live data. To coordinate modifications to Java source code, we've found that version control packages, such as CVS, RCS, or SCCS, work well with Java, just as they would work with C programs.

When several developers each run their own Locomotive, each of them can setup their own HTML template root directory, or "template root" for short. That way, they can create or modify their own appropriate templates in their own space, without having to deal with other people's modifications. You can also use version control packages to coordinate modifications to the templates. On the other hand, all the developers can use one global web server document root directory if they need to refer to graphics files, since developers seldom create or modify their own graphics. In fact, the HTML templates can refer to graphics files or other files which do not exist yet, as long as their web server and their browser do not complain.

On the other hand, the graphics designers and HTML writers modify both graphics files and HTML templates. They will need to coordinate with each other as to who is working on which files. There is also the question of when the designers can work on the HTML templates, and when the developers can work on the templates. Obviously, both should not be modifying them at the same time. One strategy that has worked before is for the developers to create a minimal "skeleton" of the HTML template, one which shows just the bare functionality that they're trying to implement -- a "proof of concept". At the same time, the designers can work on another version of the template that is pure HTML and beautiful-looking, the "mock-up". Then, at some point, the developer or the designer can merge those two versions together, by inserting the Steam commands into the appropriate places in the HTML template.

An alternative method is for the developer to create the skeleton of the template first, and then hand it off to the designer, who fleshes it all out. Either way, both the developer and the designer should ideally understand both HTML and Steam.

When you want to transfer all the changes you made on the staging site to the live site, we call that "going live" or "publishing". Before you publish, there are some things you should always remember to do.

1. Make sure that the final release of the software contains the latest code from all the developers.
2. Make sure that the final set of HTML templates contains the most up-to-date, debugged versions, and that both the developers and the designers have signed off on them.
3. Of course, you should test the staging site as thoroughly as possible, using good quality control techniques, just as you would with any software release. Make sure that all the features work together right; think about unlikely combinations of two different features that might cause problems.
4. If anyone created any new tables or other entities in the staging database, then they should create the same tables on the live database. If those tables need to contain some data, then that data should be exported from the staging database to the live database. This can be done before publishing, since having extra data on the live database is harmless.

1. Copy the graphics files, the regular HTML files, and the HTML template files all onto the live site. Do NOT copy them directly into the real working directories where they should be; rather, put them into new temporary directories. That way, you don't jeopardize any of the files being used on the live site while you're copying over the staging files. On Unix systems, you can write a script using 'tar' and 'ftp' or 'rcp' to do this automatically for you.
2. When you're ready to publish, use a script or a single long command to switch the temporary directories with the working directories. For example, in Unix, you can create an alias command to do this. That way, the switch over is instantaneous, and users will not see Web pages with inconsistent data. However, do NOT remove the former working directories, in case there is some problem with the new data and you need to switch back. Just keep them somewhere close by.
3. When you change template files while a Locomotive is running, and you want the Locomotive to continue running, you may need to send a signal to that Locomotive to tell it that you've switched template files. That's because the Locomotive doesn't read template files each time they are displayed; the Locomotive caches those files in memory to improve performance. In order to tell a Locomotive to reload its templates, you need to log into the Locomotive as a user who has "super user" privileges (your loco_users.loco_flags needs to be 7 -- see above), and then use the ServerHandler URL command:

.../locolink/srv?reload_templates

Remember to do this for ALL Locomotives on your live site, or else your site will display new pages mixed with old pages inconsistently.
4. On the other hand, if the software for the Locomotive has changed, then you need to copy over the Java class files into the class files directory for each Locomotive that is running, and then shut down and restart each Locomotive. You should do this after you've copied over all the staging templates and files, so that the Locomotive is using new data immediately. Remember to do this for each Locomotive on your live site.
5. Once you have copied all the files onto the live site, do one last check to make sure that you're seeing the new content on your web site, and then you're done.