Meteor

An HTTP server for the 2.0 web

Welcome to Meteor - you're a star! (Learn more)

Meteor home > Server documentation

How to configure / run / tweak your Meteor server to do pretty much anything. If you just want to do basic streaming, try installing first :-)

Starting the Meteor daemon

To start Meteor, use the cd command to change to the directory the meteord daemon is in, then start with:

This will run Meteor in debug mode, in which it will print out debug information to the console. If the -d flag is omitted, Meteor will start itself as a daemon. See below for a full list of possible configuration parameters.

To properly install Meteor copy the Meteor directory to one of the paths at which perl5 finds it’s modules, and copy the meteord program to any desired location from which it can be started.

Server configuration parameters

This section lists all the configuration parameters that can be set when Meteor is started. Meteor will always determine a value for every parameter, with the following precedence:

  1. Command line
  2. Config file
  3. Default

To set config parameters on the command line, start Meteor as follows:

On the command line, the parameter names are not case sensitive, and the shortest abbreviation that uniquely identifies a parameter can be used. For example the debug parameter can be shortened to d as no other parameters start with that letter. If a parameter name is given with no value a value of 1 will be assumed (and will override any conflicting setting in the config file). If you wish to set a value that starts with ‘-‘, prefix it with an additional ‘-‘. Finally, in addition to the parameters listed below Meteor supports the optional command-line only parameter -help (or -h), which outputs the following list, as well as a sample configuration file.

The configuration file can also list any of the parameters, one per line followed by whitespace and the parameter value. A leading space or tab in a parameter can be written as \s or \t respectively. Carriage returns and linefeeds must be written as \r and \n respectively. Backslashes must be doubled up. No abbreviations are allowed in the configuration file. Any lines beginning with a hash (#) character are comments and will be ignored, as are empty lines (only containing whitespace).

Some configuration parameters can be overridden for a specific connection mode. In the sample configuration file these overrides are used to define the differences between the transports that are used in various browsers. For example, streaming in Firefox uses the interactive state of an XMLHTTPRequest, while Internet Explorer loads the stream into an iframe as if it's an HTML file. As a result the messages need to be packaged differently, and that's where some of the configuration parameters can be overridden to define these differences.

To define a section of the config file that relates to a particular transport mode, enclose the mode name in square brackets (this format should be familiar to anyone that has edited Windows ini files):

The following configuration parameters can be overridden for a specific transport mode:

Note that the ConfigFileLocation parameter can only be set from the command line!

ChannelInfoTemplate
Template for each line of channel information. Channel information can be included in a HeaderTemplate using ~channelinfo~, and if included, one line of channel information will be printed for each channel to which the request is subscribed. The placeholders ~name~, ~lastMsgID~, ~messagecount~ and ~subscribercount~ can be used in the ChannelInfoTemplate and will be replaced with appropriate values. The Meteor JS client uses channel information to find out the latest message index on each channel. Format: String, Default: <script>ch("~name~", ~lastMsgID~);</script>
ConfigFileLocation
Configuration file location on disk (if any). Format: String, Default: /etc/meteord.conf
ControllerIP
IP address for controller server (blank = all local addresses). Format: Dotted decimal, Default: blank

ControllerPort
Port number for controller connections. Format: Integer, Default: 4671

ControllerShutdownMsg
Controller Shutdown message, sent to all connected event controllers when Meteor shuts down (leave empty for no message). Format: String, Default: blank

Debug
Debug Flag, when set daemon will run in foreground and emit debug messages. Options: [1|0], Default: 0
DirectoryIndex
Name of index file to serve when a directory is requested from the static file web server. Format: String, Default: index.html
HeaderTemplate
Header template, content to send to subscriber clients immediately upon successful connection, before any messages. ~server~, ~servertime~, ~status~ and ~channelinfo~ are replaced by the appropriate values. See ChannelInfoTemplate for more details about channel information. Format: String, Default: HTTP/1.1 ~status~\r\nServer: ~server~\r\nContent-Type: text/html; charset=utf-8\r\nPragma: no-cache\r\nCache-Control: no-cache, no-store, must-revalidate\r\nExpires: Thu, 1 Jan 1970 00:00:00 GMT\r\n\r\n

Help
Print a help message to standard output and exit. Options: [1|0], Default: 0
LogTimeFormat
Format in which to print timestamps on log output. Choose from unix timestamp (unix) or RFC2822 formatted date (human). Options: [unix|human], Default: human
MaxMessageAge
Maximum age of a message in seconds, after which the message will be purged from the memory cache. Format: Integer, Default: 7200

MaxMessages
Maximum number of messages to send to a subscriber before forcing their connection to close. Use 0 to disable. Format: Integer, Default: 0

MaxMessagesPerChannel
Maximum number of stored messages per channel. When this limit is reached, the oldest messages will be removed as new ones are added. Format: Integer, Default: 250

MaxTime
Maximum duration in seconds for a subscriber connection to exist before forcing it to close. Note that the server checks for expired connections in 60 second intervals, so small changes to this value will not have much of an effect. Use 0 to disable. Format: Integer, Default: 0

MessageTemplate
Message template, content to send for each event: ~text~, ~id~, ~channel~ and ~timestamp~ will be replaced by the appropriate values. Format: String, Default: <script>p(~id~,"~channel~","~text~");</script>\r\n

Persist
Whether connections should persist or be closed as soon as the first response has been made. Options: [0|1], Default: 0

PingInterval
Interval at which PingMessage is sent to all persistent subscriber connections. Must be at least 3 if set higher than zero. Set to zero to disable. Format: Integer, Default: 0

PingMessage
Message to be sent to all persistent subscriber connections every PingInterval seconds. Format: String, Default: <script>p(-1,"");\r\n</script>\r\n

SubscriberIP
IP address for subscriber server (blank = all local addresses). Format: Dotted decimal, Default: blank

SubscriberPort
Port number for subscriber connections. Format: Integer, Default: 4670

SubscriberShutdownMsg
Subscriber Shutdown message, sent to all connected subscribers when Meteor shuts down or the same client reconnects from a different source (leave empty for no message). Format: String, Default: <script>eof();\r\n</script>\r\n

SubscriberDocumentRoot
An absolute filesystem path, to be used as the document root for Meteor's static file web server. If left empty, no documents will be served. Format: String, Default: /usr/local/meteor/public_html
SubscriberDynamicPageAddress
Since Meteor is capable of serving static pages from a document root as well as streaming events to subscribers, this paramter is used to specify the URI at which the event server can be reached. If set to the root, Meteor will lose the ability to serve static pages. Format: String, Default: /push

SyslogFacility
The syslog facility to use. Format: String, Default: daemon

UDPIP
Experimental UDP server support - set this to the IP on which to listen for controller commands over UDP. Leave blank for all local addresses. Format: String, Default: ''

UDPPort
Experimental UDP server support - set this to the port on which to listen for UDP connections. Set to zero to disable UDP server. Format: String, Default: 0

Subscriber request format

Subscriber clients connect to Meteor and issue standard HTTP-formatted requests. These can be in two flavours: static page requests and data channel subscriptions. The static page web server is a very basic feature of Meteor designed simply to allow a few pages to be served from the same host/port as the data stream, which prevents cross site scripting restrictions from causing a problem. A request for a static page should be in the form:

The GET request can include querystring parameters or anchors if desired, but these will be ignored by Meteor (and are generally used for cache-busting by the client). Additional headers such as cookies and user agent strings can also be sent in the request, and will also be ignored.

Static page serving is enabled if the server config parameter SubscriberDocumentRoot is set to a valid filesystem path. Files will only be served if each component of the file path contains only the characters A-Z a-z 0-9 -_. and does not start with a dot.

Once a file has beens served once, it is read into memory along with the Meteor message queue. Further requests for the same file are handled from the memory cache. That means the files should be small.

If the requested path points to a directory, the file indicated by the DirectoryIndex variable is served if it exists in that directory.

Requests for subscriptions to channels should be in the form:

In this case the SubscriberDynamicPageAddress server configuration parameter is assumed to be push. The remaining elements of the path are:

hostid
Gives the server a unique reference for the client. The server will use this to ensure that it is only serving one response to each client and reduces the liklihood of zombie connections. If a client opens a connection of any kind, specifying an id, then any persistent connections with the same id will be closed by Meteor. Mandatory. Format: String
streamtype
The type of connection to establish. Options are iframe, xhrinteractive, longpoll, smartpoll, simplepoll Mandatory. Format: String
channeldefs
The client may subscribe to multiple channels per request, and should include a channel definition for each one. This is made up of the channel name, and then optionally, a restart command. Restart commands consist of a dot and the letter r followed by a message index number to restart at that message, the letter b followed by an offset to go back that number of messages, or the letter h to retrieve the full history of the channel. If no restart command is provided, Meteor sends only events that occur after the request is received. Valid channel def examples are: demo.r456, chatroom.b5, channel1, channel2.h. Mandatory, repeatable

The combination of the parameters above can be used to request all the possible interaction modes, eg:

Note that when short polling (using streamtype 'simplepoll' or 'smartpoll'), if the client does not request a backtrack (.b), full history (.h) or a resume (.r), then no messages will be returned because the connection will not be open for long enough for any events to occur. However, this may still be desirable. If the client does not know where to resume from and does not want to receive any existing messages, it may make a simple polling request for the channel with no suffix, and Meteor will respond with a channel information summary, enabling the client to know where to resume from on it's subsequent request.

This may sound slightly confusing. To step though it:

  1. Client wants to POLL, rather than stream (probably because it has already tried streaming and it didn't make it through a proxy or firewall). However, client is yet to receive any data and does not know what the index of the latest message is
  2. Client issues GET /push/1/simplepoll/testchannel
  3. Meteor replies ch('testchannel', 44324)
  4. Client now knows the most recent message index and can request GET /push/1/simplepoll/testchannel.r44325
  5. Meteor replies with another channel info summary and any messages with an ID greater than or equal to 44325

Event controller command protocol

Event controllers connect to Meteor on the control port, and talk in Meteor's basic command protocol. Connections are not authenticated so you should ensure that the control port is protected by your firewall. The following commands are understood:

Create a new message (and a channel if the specified channel does not exist yet).

Returns the string OK followed by a space and the number of subscribers on the specified channel.

Lists all known channels, the number of messages stored on each one and the number of current subscribers. The response has this format:

The first line indicates the command was understood. Then all existing channels are listed one channel per line. The channel name is followed by the number of messages and the number of subscribers, separated by a slash and enclosed in brackets. The string --EOT-- on a line by itself ends the listing.

Outputs activity statistics:

These stats are relative to the time the Meteor process was started and are updated as events occur, so controllers wishing to analyse time-based stats should sample the data periodically and construct a rolling average. If Meteor stats are of interest to subscribers, eg to let them know how many other subscribers are connected, a controller could periodically fire these stats back into Meteor as a channel message.

Returns the string OK and closes the controller connection.

Signals

Meteor understands the HUP, TERM, USR1 and USR2 signals:

SIGHUP
When Meteor receives a HUP signal, it will re-read the configuration file, then empty the document cache as the document root may have changed.
SIGUSR1
When Meteor receives a USR1 signal, it will empty all channel caches.
SIGUSR2
When Meteor receives a USR2 signal, it will empty the document cache.
SIGTERM
When Meteor receives a TERM signal, it will perform a clean shutdown as follows:
  1. Close the Subscriber server
  2. Close the Controller server
  3. Delete the /var/run/meteord.pid file
  4. Close all connections after sending any configured shutdown messages
  5. Exit

During a TERM procedure, Meteor will attempt to send the shutdown messages for a maximum of 120 seconds. If some clients can not be contacted during that time, it will exit with an exit value of 1. Otherwise it will exit with a value of 0.