Transmitter Configuration

Castanet transmitters deliver channels, or applications, to Castanet tuners on client machines. A transmitter is not initially loaded with channels that can be delivered to tuners, however. Before it can can deliver channels, some channels must be installed on the transmitter with the publish command.

The release contains a number of demo channels in the channels directory. In order to make these channels available on your computer, you need to invoke a transmitter on your computer and initialize the transmitter with those channels. Before you do that, however, you must configure and launch your transmitter.

Configuring a Transmitter

If you install your transmitter on UNIX as a package, you will already have specified some of the configuration parameters, but it does no harm to run the transmitter configuration and launch program again. On the PC you will need to configure your transmitter this way.

Transmitter configuration is performed by the transmitter itself, so to begin configuring your transmitter you can just run the transmitter executable with no arguments. On Win95 just launch the transmitter from Start menu. On UNIX you will need to launch the transmitter from the shell. By default the transmitter package is installed in /opt/MRBtrans, so to launch the transmitter by hand:

	prompt> cd /opt/MRBtrans
	prompt> castanet/transmitter/bin/transmitter
The transmitter will pop up a GUI which steps you through the process of configuring your transmitter. If you have problems at any stage you can press Help.

The transmitter configuration results in the creation of a properties.txt file in the transmitter root directory. If you are not in the position to run a GUI program on UNIX then you will have to hand-create a transmitter root directory and properties.txt. The format of this file will be explained below.

When you are done configuring the transmitter, you have the option to launch it. The transmitter must be running if you want to store channels on your transmitter.

Launching a Transmitter

The transmitter configuration program allows you to launch a transmitter after you have configured it. If you run the configuration program again, you can quickly step through the configuration because it remembers your defaults from the last time you did it. And don't worry about running through the configuration more than once - it doesn't hurt.

You can also launch the transmitter from the command line by simple specifying a transmitter root directory on the command line. On UNIX that would look like this:

	prompt> cd /opt/MRBtrans/castanet/transmitter
	prompt> bin/transmitter root-directory
This will start a running transmitter without popping up a gui, which is appropriate for putting in a system startup script. The UNIX package installation will do this automatically for you if you wish.

Loading the Transmitter with Channels

As stated above, a transmitter comes with no channels in it. You have to store channels in it by using the publish command. The publish command, like the transmitter, comes in GUI as well as command line options. To get started, however, it makes a lot of sense to use the publish GUI. Like the transmitter administration program, the publish program will walk you through the steps of creating a channel (or turning an existing Java program or applet into a channel), and then allow you to publish a channel to the transmitter.

See the publish documentation for a detailed description of the publish program.

Command line version of publish

If you can't run the publish gui, there is a command line version of that program that you can use on your PC or UNIX machines. The publish program is in the same directory as your transmitter program. On the PC, you should use the version of publish that is in bthe "Command" subdirectory in the directory where you installed the transmitter.

To load your running transmitter with the channels included in the release, cd into the transmitter release directory and run the publish command:

	prompt> publish channels/*
You will be prompted for information about the transmitter's host and port, what files not to store on the transmitter, and a password. Your password should match the password specified during the transmitter configuration, but if you are putting back to localhost you don't need to specify a password at all.

Testing Your Published Channel

To see if your channels were successfully uploaded to your transmitter, you can fire up your favorite browser and connect to "localhost:port" where port is the port you specified in the transmitter configuration. By default it's port 80. Our second favorite port here at Marimba is 5282. Can you figure out why?


Transmitter Directory Structure

The transmitter root directory has 4 subdirectories and one properties.txt file in it. The directories are:
channels
where channel-specific information is stored
files
a shared area where the files that make up the channels are stored
data
where channel plugins store data associated with the channel
logs
where transmitter access, error and publish logs are stored, as well as channel-by-channel log files which get their data from tuner logging.


Transmitter Configuration Parameters

The transmitter configuration program creates a properties.txt file in the transmitter's top-level directory. It contains a bunch of parameters. It is OK to hand-edit this file if you want, but if you want them to take effect you will have to stop and restart the transmitter.

The following configuration parameters are currently recognized:

server.host=hostname
Specifies the fully qualified hostname of the machine on which this server is running. You need to specify the entire domain name for the server if you want it to be visible outside your domain. This is because it is not always possible to determine the correct host name because of local DNS bindings.

server.port=portnumber
Specifies the port number on which this server is running. The default port number is 80. Make sure that external users have access to the specified machine and port number through your firewall.

server.trustedhosts=name,name,name
Specifies a list of hosts which are considered trusted by the transmitter. Trusted hosts are allowed to administer the transmitter remotely. Currently remote administration consists of updating and deleting channels on the transmitter. The hosts are comma-separated.

server.password=string
This specifies the password that is required for remote administration. If a blank password is specified, no password is required for remote administration. Local administration requires no password.

server.threads=number
The initial number of thread that are forked to service requests. The default number is 64. This number can be varied for optimal performance.

server.maxthreads=number
The maximum number of threads that can simultaneously service requests. Initially there are server.threads threads created, but if that ever turns out not to be enough, more threads will be created until server.maxthreads is reached. This parameter is currently not supported.

server.processes=number
The number of transmitter processes that should be run simultaneously. NOTE: The default number is 1, and the Java version of the transmitter currently only supports 1 process. The total number of simultaneous connections is server.maxthreads multipled by server.processes. This number can be varied for optimal performance.

server.memdisk=number
This specifies the maximum size of the in-memory cache in megabytes. This will greatly improve the performance on high volume servers. The default is 2 megabytes.

server.connection.timeout=number
This specifies the time, in seconds, that a connection is allotted to make progress. If a connection doesn't make progress within this time interval, then the connection is aborted by the transmitter and its resources are freed up for another connection. The default is 120 seconds.

server.html.listing=filename
This is the absolute pathname of a file that the transmitter will send back when a browser connects to the transmitter. This file contains descriptions and URLs of the channels served by this transmitter. If there is no file specified, which is the default, then the transmitter will generate a generic HTML page with the channel listing.


Log File Formats

The access log file (logs/log) logs subscribe, update and unsubscribe requests from tuners. The publish log file (logs/publish.log) logs hot update commands from developers. All log entries have an IP address and a time of the log entry.


Performance Considerations

For best performance you should make sure that the transmitter's channels are stored on a local disk. Using a network mounted disk significantly decreases the performance of the transmitter. Also, if you have large channels, you might want to bump up the size of the transmitter's server.memdisk property, documented above.

Note that the current implementation has only been tested under relatively low loads. Future version will support high loads and will provide NSAPI and ISAPI plugins for high volume sites.