#

## Chapter 6

## Transmitter Administration
and Performance Tuning

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

- Basic transmitter administration: starting and stopping the transmitter and changing its properties
- Advanced properties to control the resources the transmitter uses
- Transmitter log files
- Performance tuning

### Basic Administration

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.

> ####

> Note

> When 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.

> ####

> Note

> This 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 leads you through the GUI for configuring the transmitter. You can change any of the transmitter's properties at that time.
- Properties specific to the transmitter configuration are stored in a file called `properties.txt` in the transmitter's channel directory. You can edit this file by hand to change any of the transmitter's properties. Make sure you restart the transmitter after making any changes. See "Transmitter Properties" at the end of this chapter for the list of available properties in the `properties.txt` file.

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`).

> ####

> Note

> Marimba recommends that you start the transmitter at boot time rather than running it through a mechanism such as `inetd`.

Changing the Transmitter's Channel Director y

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:

- The transmitter GUI will enable you to define the transmitter's channel directory. On Windows, this is the only way to change the location of that directory.
- On Solaris, you can edit the file `/etc/transmitter.conf`. That file contains two properties: `server.installdir`, whose value is the transmitter's installation directory, and `server.datadir`, whose value is the channel directory. Change the latter property to the new channel directory, save the file, and restart the server to reflect the changes.

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.

### Advanced Transmitter Configuration

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.

> ####

> Note

> Although 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.

### Transmitter Logging

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:

- Access logs (in a file called `log`)
- Error logs (in a file called `errorlog`)
- Channel publishing logs (in a file called `publish.log`)
- Logs for individual channels (named for the name of the channel, with a .log extension–for example, `MyChannel.log` or `Crossword.log`).

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:

- The IP address of the host that made the request.
- A unique tuner identifier. Each individual tuner has its own ID; you can use this to track individual users of a channel that may be connecting from the same host or through a proxy server.
- The date and time of the request.
- The type of operation that occurred, inside quotes. The most important part is the part in between the POST and HTTP/1.0; this contains the name of the channel and the operation (this one is upd for an update request). The format will always be `/`channelname`/`operation.
- The HTTP result code.
- The number of bytes transferred.
- The number of milliseconds it took from start to finish to transfer the bytes.
- The Castanet protocol version.
- An optional comment, the value of which depends on the command. Updates, for example, have comments of `manual` for manual updates, or `hour`, `minute`, `day`, and so on.

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:

- The IP address of the host using the publish tool (`127.0.0.1` is localhost, the same system as the transmitter)
- The date and time
- The user name and host of the person using the publish tool
- The name of the channel

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:

- Make sure that all the transmitter's files are contained on local disks, as opposed to network-mounted volumes. This includes both the transmitter software itself as well as the channel directories.
- Increase the threads property for your transmitter, either by using the administration tool (in the advanced properties) or modifying the `server.threads` property in the `properties.txt` file. (You might have to add this property if you're changing it from the default.) More threads means that your transmitter can handle more simultaneous connections.
- Increase the memory cache property using the administration tool or my modifying or adding the `server.memdisk` property to `properties.txt`. This will be particularly useful for very busy transmitters that publish very large channels.
- Consider dedicating a system to the transmitter (as opposed to sharing resources with other Internet services). Add more memory or upgrade the server itself.
- Very large channels that are very frequently updated can severely impact transmitter performance. Consider attempting to make the channel smaller or reducing the update frequency.
- Make sure you're not hitting transmitter limits. The standard transmitter is restricted to 100 unique users (tuners) per hour. (Those users can make as many connections as they want, but only 100 per hour can access the transmitter.) You can add another 100 users per hour by purchasing extra licenses from Marimba or by upgrading to an unlimited 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.

### Summary

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.