
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.
- Update requests
- IP-address of tuner.
- Date and time.
- Tuner ID string.
- Tuner protocol version.
- Bytes transferred / Request duration in milliseconds.
- Request type. This is UPD for update, or UPD/OPT/T or UPD/OPT/F
for an optimized update request that either succeeds (T) or fails (F).
N FILES indicates a file data request for the specified number
of files.
- Channel name.
- Optional comment.
- Hot updates
- IP-address of host doing the publish.
- Date and time.
- The name and host:port of the user performing the publish.
- Channel being updated.
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.