Using the information on installing and configuring the Castanet Transmitter from the previous two chapters, you could go happily on your way publishing and broadcasting channels and never need anything else (except the occasional update to the software). In this chapter, however, you'll learn how to fine-tune the transmitter and its features to better suit your needs and help make sure your transmitter is running smoothly. In this chapter, you'll learn about
For the most part, the Castanet Transmitter runs itself; it just starts and works (unlike, say, a pet, which you occasionally have to feed and walk and clean up after). However, you should be familiar with the basic administration tasks the transmitter does need, including starting and stopping the transmitter or reconfiguring its properties.
Starting and Stopping the Transmitter
In both Windows and Solaris, starting the transmitter either from the command line or via the Start menu brings up the transmitter configuration GUI, at the end of which is a screen that lets you start and stop the transmitter. (See Figure 6.1.) From this screen, you can temporarily stop the transmitter from accepting connections.
NoteWhen the transmitter configuration GUI appears, you don't have to change anything in the configuration screens; just keep pressing Next until you can launch the transmitter.
Figure 6.1. Starting and stopping the transmitter.
On Windows, you can bring up the transmitter GUI at any time while the transmitter is running by double-clicking on the transmitter icon in the taskbar. (See Figure 6.1.) The transmitter window will then either appear on the screen or as a taskbar entry.
Figure 6.2. The transmitter icon.
On Solaris, you can iconify and de-iconify the transmitter window to hide or show it.
Using The command line to Start the Transmitter
Usually when you start the transmitter, the administration GUI will pop up and you'll have to page through the screens to actually start the transmitter. In both Windows and Solaris, you can start the transmitter with a single argument–the transmitter's channel directory–and avoid the GUI.
In Windows, you can start the transmitter without a GUI by creating a shortcut to the Transmitter.exe program in the Castanet Transmitter directory, and edit its properties (right-click on the icon and choose Properties from the menu). In the Shortcut panel, add the full directory path to your transmitter's channel directory to the end of the Target field (with quotes around it if there are spaces in that pathname), and choose OK. That shortcut will now launch the transmitter without the GUI.
NoteThis solution is less than ideal, because not having a GUI means that you cannot stop or start the transmitter on demand and that the transmitter icon will not appear in the taskbar. To quit the transmitter you'll have to use Ctrl+Alt+Delete. Select the transmitter from that list and choose End Task. The functionality of the transmitter without a GUI will improve in future versions of the transmitter.
On Solaris, you have a couple different command lines you can use. The first is to give the transmitter's channel directory as an argument to the transmitter program, like this (here I'm assuming that you're in the transmitter/bin directory or that you have that directory in your execution path, and that your transmitter's channel directory is /usr/local/channels):
transmitter /usr/local/channels/
If you installed the transmitter software using the pkgadd version of the install, there is also a script for starting and stopping the transmitter located in /etc/init.d. You can use this script to start up the transmitter or, if the transmitter is already running, to start or stop its execution. To start the transmitter, use start as an argument to this script:
/etc/init.d/transmitter start
To stop the transmitter, use stop as the argument:
/etc/init.d/transmitter stop
Reconfiguring Transmitter Properties
When you installed and started the transmitter for the first time, you configured the transmitter with its basic information: its host name and port, its channel directory, and so on. If any of this information changes, you'll need to reconfigure the properties for the transmitter. You can do this in one of two ways:
Starting the Transmitter at Boot Time
If you installed the transmitter on Windows or if you used the pkgadd version of the installation on Solaris, the transmitter will start automatically each time you boot up your machine. (In Windows you had a choice whether or not to enable this function.)
To disable this feature in Windows, remove the shortcut to the Castanet Transmitter, which is contained in the folder Windows\Start Menu\Programs\StartUp.
If you chose not to have the transmitter start automtically in the installation, you can enable this option by creating a shortcut to the transmitter program in Castanet Transmitter\Transmitter.exe and putting that shortcut in the folder Windows\Start Menu\Programs\StartUp folder.
Startup in Solaris is determined by a link in the directory /etc/rc3.d (usually called S19transmitter). That link points to the transmitter script in /etc/init.d. To prevent the transmitter from being launched at boot time, remove the symbolic link (and, by extension, enable startup at boot time by creating a symbolic link from /etc/init.d/transmitter to /etc/rc3.d/S19transmitter).
NoteMarimba recommends that you start the transmitter at boot time rather than running it through a mechanism such as inetd.
Changing the Transmitter's Channel Directory
If, for any reason, you need to change the transmitter's channel directory (where channels and logs are stored), you can do this in one of two ways:
Keep in mind that if you change the transmitter's channel directory, you will have to reset the properties for that transmitter, including its password and trusted hosts, and republish the channels that were available on that transmitter.
Quitting the Transmitter
To quit the transmitter, choose the Exit button from the main transmitter window. Note that in Windows, selecting the close box will only hide the transmitter window; as long as the transmitter icon appears in the right side of the task bar, the transmitter is still running.
In addition to the standard set of properties you configured as part of the transmitter installation or configuration, there are several other properties that determine how many resources the transmitter will use on your system.
You can access these properties using the transmitter configuration GUI. After paging through the standard properties, the panel for "Transmitter Setup Complete" will appear. From here, choose the button labeled Advanced (see Figure 6.3) to access the advanced properties. Currently there are two advanced panels for transmitter concurrency and transmitter cache.
Figure 6.3. Advanced properties.
Transmitter Processes and Threads
The Transmitter Concurrency properties, as shown in Figure 6.4, are used to determine how many processes and threads the transmitter uses, the combination of which determines how many simultaneous connections the transmitter can process.
Figure 6.4. Transmitter concurrency properties.
The Processes field is the number of processes each transmitter uses on the server. Currently the Castanet Transmitter can only have only one process (although you can change the value of this field). Future versions of the transmitter will support multiple processes for better performance.
The Threads and Max Threads field indicate the number of separate threads per process that will handle incoming connections. The number of threads times the number of processes determines the total number of simultaneous connections that can occur on a transmitter (but, because at the moment you can only have one process, that number is simply equal to the number of threads). Currently, only the value of Max Threads is used. The default value is 32.
Setting the threads to be a larger number will allow the transmitter to handle more connections, but each thread will use some amount of CPU time and memory on the system. Depending on how busy your transmitter is and what else you want to do on that machine, you may want to set this value higher or lower: lower for better performance on the machine itself, higher for better transmitter performance to tuners accessing that machine.
NoteAlthough changing the number of threads allows your transmitter to process more connections, that value has a cap if you're using a transmitter that only allows in a certain number of users per hour.
Transmitter Memory Cache
On the next panel in the advanced properties is the transmitter memory cache (as shown in Figure 6.5). The memory cache is used to store popular channels in random-access memory, which makes them faster to access by tuners than if they were always read from the disk. The value of this number is megabytes of memory that should be used for the cache.
Figure 6.5. Transmitter memory cache.
A higher number for the memory cache means that more channels can be stored in memory, which improves performance for very high-volume transmitters. However, that memory becomes reserved for transmitter use, which means it is not available to other programs running on that server. Depending on the resources you have available for your transmitter and how popular that transmitter is, you may want to set this number higher or lower than the default.
The default value for the memory cache is 4MB.
Setting the Connection Timeout
In any connection between the transmitter and a tuner or a browser, queries and data are exchanged fairly regularly. If, for whatever reason, the tuner or the browser stop responding (due to network lags or system failure), the transmitter will wait for a short time and then free up the thread for another connection. That "short time" is called the connection timeout. By default, that value is 120 seconds (two minutes). You can set the connection timeout for your transmitter to wait more or less time, depending on how you want your transmitter to react. (For example, if you're on a not-very-stable Internet connection, you might want to increase the timeout interval to account for that network stability. If you're on a very busy transmitter, you might want to decrease the timeout to give more tuners a chance to connect.)
To set the connection timeout to something other than 120 seconds, you must add the server.connection.timeout property to the transmitter's properties.txt file, contained in the transmitter's channel directory (there isn't a panel for it in the transmitter administration tool). The value of server.connection.timeout is a number representing the number of seconds to wait for the Timeout. For example:
server.connection.timeout=180
This line will set the connection Timeout to 180 seconds (three minutes). Remember to restart your transmitter after making any property changes.
Setting the Default HTML Page
In addition to broadcasting channels, transmitters also respond to requests from Web browsers. When you contact a transmitter using a Web browser, either directly from the browser or by using the Browse button from inside the tuner, the transmitter responds with an automatically generated listing of the channels available on that transmitter, including the descriptions of those channels. Figure 6.6 shows an sample page from Marimba's transmitter.
Figure 6.6. A Browser listing of channels.
If you'd like to customize the page that your transmitter sends back to browsers, you can create your own Web page and then tell the transmitter to send that page to the browser instead. Note that if you do create your own page, that page will not be automatically updated as you add and remove channels from the transmitter (as happens with the automatically generated Web page); you will have to update the HTML page yourself each time there is a change to your transmitter listing.
To change the default HTML page the transmitter sends to a browser, first create that page and store it somewhere on your file system (the transmitter's channel directory is a good place). Make sure it has an .html or .htm extension so it will be recognized by the transmitter as an HTML file.
Then, edit the properties.txt file in your transmitter's channel directory and add the property server.html.listing to that file with the full path name to the HTML page, like this:
server.html.listing=/usr/local/channels/index.html
In this example, my new page is located in /usr/local/channels and is called index.html.
Don't forget to restart the server to pick up the changes.
A Summary of Transmitter Properties
All the transmitter properties are stored in a file called properties.txt, stored in the transmitter's channel directory. You can edit this file by hand, or the transmitter configuration GUI will edit them for you. Note that the transmitter password is encoded and must be set by the GUI.
Table 6.1 shows a list of the available properties you can set in the properties.txt file.
Table 6.1. Transmitter properties.
Property Value
server.host=hostname The fully qualified host name of the transmitter, as defined by DNS.
server.port=portnum The port number on which the transmitter runs, by default port 80.
server.password=password The password for the transmitter, encoded. You must use the transmitter GUI to change this value.
server.trustedhosts=host,host,host
A list of remote hosts that are allowed to publish channels on this transmitter, separated by commas.
server.threads=number The initial number of threads to create to handle incoming connections. The number of processes times the number of threads determines the total number of simultaneous connections that can occur on the transmitter.
server.maxthreads=number The maximum possible number of threads that can be created on the transmitter. This property is not currently used.
server.processes=number The number of transmitter processes that can handle incoming connections. Currently you can only have one process.
server.memdisk=number The number of megabytes of memory to set aside for the channel cache. A higher number improves transmitter performance.
server.connection.timeout=number
The number of seconds to wait before the transmitter times out on a connection. By default the number is 120; a lower number means the transmitter will not wait as long for a response from a tuner.
server.html.listing=filename
The absolute path of a page to use for the listing of the channels in a browser. By default, the transmitter generates this page on the fly using the names of the available channels and the channel descriptions. By replacing that default page you will have to create this information on your own.
Nearly every transaction that occurs with your transmitter–both from the tuner and the publish side–is logged in special files in your transmitter's channel directory. By monitoring these files, you can keep track of how much your transmitter is getting used, what its being used for, as well as track information for individual channels (if those channels have been defined to set logging information). If you're developing channels, often the logs can help you figure out what's going on and when.
Depending on how often your transmitter is used, you might occasionally want to move these logs elsewhere or delete them altogether to make sure they don't take up too much space on your server. Make sure you restart your transmitter after you do this so the files can be reset.
All the transmitter log files are contained in the folder or directory called logs inside your transmitter's channel directory. There are four kinds of log files that are stored:
All of these logs are simple text files, with one log entry per line. You can use scripts to process these logs to compile statistics, or simply examine them occasionally with any text editor. The contents of each log are described in the following sections.
Access Log Files
The access log file, called log, contains information about basic transmitter actions and requests. The format of the log file is identical to the common log format used by Web servers, so you can use any of the Web server administration tools to compile statistics about your transmitter. More specifically, a log file entry looks something like this (all on one line; I've broken this one up to fit on the page):
140.174.94.6 - fz8oy6uhv1xt [16/Dec/1996:18:10:11 -0800]
"POST /Crossword/upd HTTP/1.0" 200 39674 2630 v10 subscribe
There are nine parts to this log entry. Those parts are, in order:
In addition to the standard update-log entries, there are also entries for each listing request (either from a tuner or from a browser) that look like this:
140.174.94.6 11/8-00:46:31 HTML index fetched
Each time the transmitter starts, you'll also get a log entry to that effect. When compiling statistics on the access logs, you might want to screen out these lines, which look something like this:
Transmitter starts: trans.lne.com:5282 Web Dec 25 10:22:26 1996
Error Log Files
The error logs are stored in a file called errorlog. The error log contains any errors received by the transmitter, which can include connection timeouts, missing files, or Java stack traces from corrupt channels. Each error includes the IP address of the tuner that caused the error, the date it occurred, and an error message. For example:
140.174.94.6 12/25-21:19:45 Connection timed out
Publish Log Files
The publish log files keep track of channels that have been published or updated on the transmitter; each time someone uses the publish tool or command to update a channel, it's logged here.
Entries in the publish log file look like this:
127.0.0.1 11/23-15:10:19 lemay@despair.lne.com Crossword
There are four entries in each line, which represent:
Channel Log Files
The final kind of log files available in the transmitter's channel directory are the log files for individual channels. A channel will keep logs only if it has been written to do so, and the contents of those logs will vary from channel to channel. I won't cover those log files here; you'll learn how to write channels that keep logs in Chapter 12, "Creating Transmitter Plug-Ins."
Improving Transmitter Performance
When you've got a transmitter up and running and people are happily subscribing to your channels, you might discover that your transmitter isn't running quite up to speed–perhaps people are having difficulties connecting, or perhaps updates are slower than they should be. Here are some simple hints for improving the performance of your transmitter:
In addition to these suggestions, there may be additional Marimba products that can help with very high-load transmitters. In particular, the Castanet Repeater, which was described in Chapter 1, can distribute the load on a transmitter to multiple mirrors while still providing a single interface for tuners. If most of your transmitter load is coming from a few sites, you can install a Castanet Proxy server to help take some of the load off your transmitter's system, assuming, of course, that you have control over the site where most of the connections are coming from. Otherwise, you'll have to encourage the administrators of that site to install a Castanet Proxy for you.
And, finally, future versions of the transmitter will be available as native executables (the current version is a Java application) or as a Web server plug-in (NSAPI for the Netscape servers and ISAPI for Microsoft's Internet Information Server). These transmitter versions will improve overall transmitter performance as well.
Running a transmitter involves more than just installing the software and publishing channels. Fortunately, it doesn't involve a whole lot more than that. Other than the occasional tweak to the properties or a check of the logs to make sure not too much is going wrong, there's little you'll need to do to coax a transmitter into running effectively.
Despite that statement, however, in this chapter you learned the few things you will need to know about transmitter administration, whether you're both the channel developer and the administrator or if you just keep the transmitter going so others can use it. Starting and stopping the transmitter, modifying its properties, and understanding the entries in the log files–all of these things can help you manage a transmitter more effectively and help to run smoothly.
This chapter brings to a close Part II and the end of the basic description of how to use the Castanet framework software. In Part III, we'll get into the good stuff–learning how to develop and maintain your own channels.