#

## Chapter 4

## Installing and Configuring the Transmitter

The Castanet Transmitter is the other half of the Castanet technology. The transmitter is the tool that makes channels available on the Internet for tuners to subscribe to. If you develop your own channels or support channel developers, you'll need to install a Castanet Transmitter on an Internet-accessible system and then publish your channels on that transmitter.

In the next three chapters, you'll learn all about installing and administering the Castanet Transmitter, as well as how to add and maintain channels. (You'll learn how to actually write the channels in Part 3.)

### Before You Start

As with the installation for the tuner, let's first go through and make sure you've got the ingredients to install everything successfully.

- Make sure you have the right system requirements. For Windows you'll need a Windows 95 or Windows NT 4.0 system with at least 8MB of memory and 10MB of free disk space. For Solaris you'll need to be running Solaris 2.4 or higher with 16MB of RAM and 10MB of free disk space (again, more if you've got lots of channels).

> ####

> Note

> Currently, Marimba supports transmitters on these platforms only. However, several other unsupported ports of the Marimba software are also available for other UNIX systems such as Linux and FreeBSD. See `http://www.marimba.com/products/unsupported.html` for more details.

- Make sure the system you install the transmitter on is accessible to the Internet at large. (Or, if you're publishing channels for intranet use only, your transmitter should be accessible to those systems inside your network that will be using it.)

For either Internet or intranet use, you will need the fully qualified host name of that machine (that is, starting with the system name and including the domain name). Transmitters often have a name with the prefix "trans" (for example, `trans.marimba.com`). You can set up a DNS alias (CNAME) for your transmitter to follow this convention.

> ####

> Note

> Keep in mind that transmitters should be accessible to tuners 24 hours a day, 7 days a week. If your only connection to the Internet is a dial-up PPP or other part-time connection, you might want to locate an ISP that supports transmitters for your channels rather than install your own transmitter.

- You can install the transmitter for personal testing use on a system without a network connection (for example, if you want to make sure your channels are working before installing them somewhere else). On Windows, however, you will need to use the Network control panel to make sure that the TCP/IP Protocol is installed, and that DNS is disabled.
- Pick a port number that the transmitter will run on. By default, the transmitter runs on port `80`. This enables Web browsers to get a channel listing from your transmitter (Web servers typically run on port `80`). If you already have a Web server running on port `80`, you'll need to pick another port number. Conventionally, transmitters run on port `5282` when they can't run on port `80`. If your transmitter is running on a firewall system, you'll have to open access to the transmitter's port so that tuners can get to it.

> ####

> Note

> On Solaris, if you do not have access to root (superuser), you will have to install the transmitter on a port number higher than `1024`. (`5282` will do just fine.)

- Choose a directory to store channels in. This directory is usually separate from the transmitter software itself. On Windows, it's typically `C:\Marimba\Transmitter`; on UNIX it can be anywhere you want it to be. Note that for best transmitter performance, channels should be located on a local disk (as opposed to one mounted over a network).
- Do you have a Web browser available? The transmitter documentation and help files are available as Web pages (and as a channel from Marimba's transmitter). You will need a Web browser such as Netscape or Internet Explorer to view these pages.

###
Installing and Configuring the Transmitter

After you've assembled or found out all the information from the last section, you can install the transmitter software on the system that will serve as your transmitter. There are two places you can get transmitter software:

- On the CD-ROM that comes with this book.
- From Marimba's Web site at `http://www.marimba.com/`.

> ####

> Note

> The transmitter contained on the CD-ROM for this book is a limited version that only allows five unique users per hour to connect to the transmitter. (Each of those users can make unlimited connections, but once the limit is reached, new users will be turned away.) This version is intended for you to use it for testing and for trying out the software; if you're creating channels for public consumption, you'll want to look into using the commercial version of the transmitter, which allows 100 unique users per hour (or more, for additional cost).

For Windows, the transmitter is an executable file called `Trans1_0.EXE`. On Solaris, there are two transmitter installation files, both compressed tar archives. The first, `transmitter1_0_pgk_tar.Z`, is intended for use with the `pkgadd` program and can only be run installed as root. The second, `transmitter1_0_tar.Z`, can be unarchived anywhere and can be used by any user on the system.

Skip to the section that describes the installation for your system.

Installation of Windows

To install the transmitter on Windows 95 of Windows NT, first quit all running Windows programs (particularly the Castanet Tuner, if it's running), and double-click the installer file. Windows will load the transmitter installer wizard.

> ####

> Note

> If you're using the transmitter installer from the CD-ROM that came with this book, you can find the transmitter installer in the directory `Marimba` and then in the subdirectory for your platform (`Win95`, `WinNT`, or `Solaris`)—for example, `Marimba\Win95\Trans1_0.EXE`.

The Castanet Transmitter installer wizard will lead you through the installation, including choosing an installation directory. (See Figure 4.1.)

Figure 4.1. Choosing an installation directory.

By default, the transmitter software is installed into `C:\Marimba` (also the default location for the tuner). You can install it anywhere on the system where you have disk space available.

After all the transmitter files have been installed, you are asked if you would like to have the transmitter start automatically when you reboot. Because the transmitter should be available to tuners that may want to access it at any time during the day or night, it's a very good idea to choose Yes for this option so you don't always have to remember to start up the transmitter when the system reboots. If you choose No, you can add a shortcut to the transmitter to the StartUp folder later; see Chapter 6, " Transmitter Administration and Performance Tuning" for details.

After the installation process is finished, skip to "Starting, Configuring and Testing the Transmitter" to finish getting the transmitter up and running.

Installation on Solaris with pkgadd

The preferred method of installing the transmitter on Solaris is with the `pkgadd` program (part of the standard Solaris operating system.). You will, however, need to be root to run `pgkadd`. If you do not have root access on your system, skip to the next section, "Installation on Solaris without `pkgadd`."

Before you can run `pkgadd` to install the transmitter, you'll need to uncompress and un-tar the installation archive file into some temporary location (for example, `/tmp`). These lines do just that:

`mkdir /tmp/trans
cp transmitter1_0_pkg_tar.Z /tmp/trans
cd /tmp/trans
uncompress transmitter1_0_pkg_tar.Z
tar xvf transmitter1_0_pkg_tar`

The contents of the `tar` archive will be extracted and installed into the directory `/tmp/trans`. Then, run `pkgadd` with that directory as an argument:

`pkgadd -d /tmp/trans`

You'll get a message similar to this one:

    The following packages are available:

      1  MRBtrans     Marimba Transmitter

                      (sun4) 1.0beta2

    Select package(s) you wish to process (or 'all' to process

    all packages). (default: all) [?,??,q]:

Choose 1 and press Return.

You'll be asked to agree to a user agreement, and then the install script will ask you to choose an installation directory:

    First, choose a directory to install the transmitter binaries, and

         the Java Virtual Machine.  This normally would go somewhere under

         /opt.  This is called the "package base directory."

`
Enter the package base directory [/opt/MRBtrans]:`

Packages, under Solaris, are traditionally installed in the `/opt` directory, but you can install the transmitter software anywhere you have room—for example, `/usr/local` or `/export/home`.

In the next step you're asked to choose a channels directory, which is used to store the channels that you've published on your transmitter. It should not be the same directory as your transmitter software; if you have to upgrade the transmitter, you don't want to overwrite all your channels. Choose some other directory for channel use. For best performance, that directory should be located on a local disk (as opposed to one mounted over the network). Here I chose the directory `/usr/local/channels`:

> `Please select the transmitter's channel directory. This is the directory that stores the channels that the transmitter broadcasts. For optimal performance, this directory should be located on a local file system. There must be more than enough free disk space to store the data for all channels.`

`Enter the transmitter channel directory: /usr/local/channels`

`
` The next two steps are to enter the fully qualified host name of the transmitter's system and the port number on which the transmitter will run. Keep in mind that if you already have a Web server running, you'll need to use some port other than 80—5282 is the traditional alternative port number. In this example I've used `trans.lne.com` as the host name of my server, and 5282 for the port.

`Enter the fully-qualified host name [.]: trans.lne.com
Enter the port number [80]: 5282`

> ####

> Note

> The host name you use for the transmitter must already be an existing host name for that site. (If it doesn't exist, your tuner won't be able to connect to that system.) Typing it here will not modify your network setup to include that name, so make sure you choose a name that already exists.

The last couple of steps involved setting a transmitter password and a list of trusted hosts for publishing to this transmitter. You can use these options to restrict who can publish to this transmitter.

The first option is the transmitter password. If you set a transmitter password, you can restrict who has access to publishing on this transmitter. (You can also control access to individual channels, but you'll learn about that in Chapter 5, "Installing and Publishing Channels.") You don't have to set a transmitter password if you don't want to.

> ####

> Note

> If you'll be publishing channels from the same system on which the transmitter is running, you cannot set a password to restrict transmitter access (or rather, you can set one, but it won't be used). The password only applies to people publishing the channels from remote systems; The transmitter is open to anyone running on that same system.

The list of trusted hosts is also used to restrict access to the transmitter. Only host names that you enter in this list will be allowed to publish to the transmitter -- regardless of whether or not they have a password. Use localhost to restrict publishing access to the same machine the transmitter runs on, or don't enter any hosts to allow open access to the transmitter.

> ####

> Note

> You can always change the password or list of hosts later, so don't worry about getting it right this time.

Enter the password at the prompt, and then each host name at each individual prompt, with a return to stop entering host names:

    Please specify a password and a list of trusted hosts.  These will be

         required in order to create, putback, and delete channels on this

         transmitter.  If no hosts are specified, then any host may perform a

         putback.  To restrict access to only this host, list either this

         host's name, or "localhost".

    Enter a password:  [?,q]

    Enter a trusted host name (blank line to finish): localhost

    Enter a trusted host name (blank line to finish):

If all goes well, the transmitter software will be installed and you'll be returned to the "Select package(s) you wish to process" prompt. Choose q to quit the installation.

To start and run the transmitter, skip ahead to "Starting the transmitter from the command line."

Installation On Solaris Without pkgadd

If you don't have access to root on your system or can't stand the `pkgadd` interface, you can install the transmitter software by hand.

The installation archive for this purpose is called `transmitter1_0_tar.Z` (not `transmitter1_0_pkg_tar.Z`). Copy that archive to your chosen installation location and decompress it:

`cp transmitter1_0_tar.Z /usr/local/
cd /usr/local/
ncompress transmitter1_0_tar.Z`

Then use `tar` to extract the files from the archive.

`tar xvf transmitter1_0_tar`

> ####

> Note

> In this example, I've installed the transmitter in the same location that I installed the tuner in Chapter 2; both products will end up located in the `/usr/local/castanet` directory.

Once you're done, you can delete the tar archive:

`rm transmitter1_0_tar`

Go on to the next section to finish setting up the transmitter.

### Configuring the Transmitter

If you installed the transmitter on Windows or on Solaris without using `pkgadd`, the next step is to configure it so that it can run. The transmitter comes with a configuration program built in; all you have to do is start it to step through the process.

> ####

> Note

> If you installed the software using `pkgadd`, you've already configured the transmitter for basic operation, so you can skip this section. However, should you ever need to reconfigure the transmitter to have different values, you can use the procedures described in this section.

To start the transmitter on Windows, navigate through the Start menu to the transmitter program. (See Figure 4.2.)

Figure 4.2. Starting the Castanet Transmitter.

To start the transmitter on Solaris, run the transmitter program contained in the transmitter directory hierarchy. For example, if you had installed the transmitter software into `/usr/local/`, you'd start the transmitter with this command:

`/usr/local/castanet/transmitter/bin/transmitter`

On both Windows and Solaris, the transmitter displays an initial window. Chose Next to proceed to the first configuration screen.

Setting the Transmitter Directory

This first screen, shown in Figure 4.3, is used to set the transmitter's channel directory.

Figure 4.3. Transmitter channel directory.

The root directory is used to store all the channels that are available on the transmitter. It should not be the same directory as your transmitter software; in case you have to upgrade the transmitter you don't want to overwrite all your channels. Choose some other directory for channel use. For best performance, that directory should be located on a local disk (as opposed to one mounted over the network).

On Windows, the default channel directory is at `C:\Marimba\Transmitter` (note that this is different from the default install directory, which is `C:\Marimba\Castanet Transmitter`). On Solaris, you can put the channel directory anywhere you'd like (for example, `/usr/local/channels` or `/usr/local/castanet/transmitter_channels/`).

Setting the Transmitter Host and Port

Choose Next to go to the next screen: The transmitter host and port window, shown in Figure 4.4.

Figure 4.4. Transmitter host and port.

In this window, enter the fully qualified host name of the transmitter and the port number on which it runs. (A fully qualified host name is one that ends with your domain name—for example, `trans.marimba.com` or `trans.mysite.org` as opposed to just `trans` or `www` or some other shorter host name.) If you're installing the transmitter on a system without a network connection, for local testing, you can use localhost as the transmitter name.

Also enter the port number which the transmitter will run on. On Solaris, if you're using a port number less than `1024`, you must be running this configuration program as root; otherwise you're restricted to port numbers over `1024` (for example, `5282`). Keep in mind that although the default port is `80`, if you already have a Web server on that port you'll have to choose a number other than `80`.

Setting Transmitter Access Control

The next screen, shown in Figure 4.5, is for controlling access to who can publish on this transmitter. It includes setting a password and defining a list of trusted hosts.

Figure 4.5. Transmitter access.

First, enter the transmitter, if needed. If you set a transmitter password, you can restrict who has full access to publishing on this transmitter. The transmitter password is similar to a root password for this transmitter; anyone who has the transmitter password has full access. (There are also channel passwords, for publishing specific channels; you'll learn about these in Chapter 5, " Installing and Publishing Channels.") You don't have to set a transmitter password if you don't want to.

Second, enter a series of host names (again, fully qualified host names) of systems that are allowed to publish or update channels on a transmitter. If you have a separate system for channel development, for example, you might put the name of that system here. Use `localhost` for the host the transmitter is installed on, or leave this field blank to allow any system that can access your transmitter to publish channels on that transmitter.

Setting Publish Notification

Choose Next to move on to the Publish Notification screen (shown in Figure 4.6). The address shown in the e-mail address window is a special address at Marimba to let them know when you've published a channel. If you don't want to tell Marimba about new channels or you're inside a firewall and cannot send mail to the Internet, delete this address and leave that field blank.

> ####

> Note

> The picture shown in Figure 4.6 is actually labelled Putback Notifications; Putback is the previous name of the Publish tool. They are the same thing.

Figure 4.6. The Publish Notifications Screen.

If you do leave the address in place, fill in the SMTP field with the name of your mail host. This is often the same mail host where your e-mail program checks for mail.

Confirmation

The last screen is simply a confirmation of the basic properties for the transmitter. (The Advanced button is used to set advanced properties of the transmitter; you'll learn about these properties in Chapter 6, "Transmitter Administration and Performance Tuning.") Choose the Launch button to start the transmitter actually running. The window shown in Figure 4.7 will appear after the transmitter is active and running on the system.

Figure 4.7. A running Transmitter.

When the transmitter is running, a transmitter icon will appear in the task bar. (See Figure 4.8.) You can show the transmitter window at any time by double-clicking that icon.

Figure 4.8. The icon for a running transmitter.

### Testing a Running Transmitter

You can test to see if the transmitter is working at this point by starting up a tuner and connecting to the transmitter from the Listing panel using the transmitter name you entered in the configuration. (Don't forget the port number if it was something other than `80`!) Use the localhost for the name of the transmitter if you're running both the transmitter and the tuner on a local system with no network connection. You won't get a channel listing (you haven't published any channels yet; you'll do that in the next chapter) but the status bar in the lower right should say "Listing Empty." (See Figure 4.9.)

Figure 4.9. Running Transmitter (no channels yet).

If you get no response from the transmitter or a Connection failed error, make sure the transmitter name you're using actually does point to that system and that the system is reachable over your network. If it is reachable, make sure the transmitter is running and that its running on the port that you think its running on. If you're still having problems, make sure that you don't already have something running on the port where you installed the transmitter (for example, a Web server), which would prevent the transmitter from replying, and change the port for the transmitter if necessary.

If you're using a system without a network connection, make sure that you've disabled DNS (using the Network Control Panel, double-click the entry for TCP/IP and switch to the DNS panel), and that you've used localhost as the name of the transmitter in the transmitter configuration and as the name of the transmitter in the tuner.

### What Gets Installed, and Where

On Windows, the transmitter installer creates two directories. The main software directory, typically `C:\Marimba\Castanet Transmitter`, contains the main transmitter software. The second is the transmitter's channel directory where channels are stored; that directory is typically `C:\Marimba\Transmitter`. Both these locations can be changed via the installation or configuration programs.

After you configure the transmitter, that configuration information is stored in a file called properties.txt in the transmitter's channel directory. You can edit it directory using your favorite text editor or using the configuration tool; you'll learn more about configuring the transmitter in Chapter 6, "Transmitter Administration and Performance Tuning."

If, during the Windows installation, you agreed to let the transmitter start up when you reboot the machine, a shortcut to the transmitter program is stored in Start menu. To prevent the transmitter from being started on reboot, choose Start | Settings | Taskbar | Start Menu Programs, and then click Remove. Navigate to the StartUp folder, click Castanet Transmitter, and choose Remove.

On Solaris, if you install the software using `pkgadd`, several things are installed for you:

- The main transmitter software is installed into `/opt/MRBtrans/`, or into the directory you chose for the `pkgadd` base directory.
- The transmitter's channel directory is created for you.
- Your transmitter configuration information is stored in a file called properties.txt in the transmitter's channel directory. You can edit that file with a text editor, or modify its values using the transmitter GUI program.
- A script for starting and stopping the transmitter is located in `/etc/init.d`.
- Basic transmitter configuration is stored in `/etc/transmitter.conf`.
- Your `rc` files are modified to start the transmitter when the system boots.

If you install the transmitter without `pkgadd`, the transmitter software is installed into the location where you expanded the tar archive. After you run the configuration program, your transmitter's channel directory is created and the configuration information is stored in a `properties.txt` file in that directory.

### Uninstalling the Transmitter

There might be cases wherein you'll want to remove the transmitter software from your system—for example, to reinstall a new version of the transmitter or to "decommission" a former transmitter system.

To remove the Castanet Transmitter from Windows, choose the Add/Remove Programs from the Control Panels, and select the transmitter from the list. (See Figure 4.10, which shows an old transmitter beta being removed.) Finally, choose the Add/Remove button to remove the software. You'll be asked if you want to remove the transmitter's channel directory in addition to the regular software.

Figure 4.10. Uninstalling the transmitter.

There are two ways to remove the transmitter from Solaris, depending on whether you installed it using pgkadd or used the regular installation. If you had used `pkgadd` to install the software, you can use the pkgrm command to remove it. Simply type `pkgrm` alone at a Unix prompt. You must be root to run `pkgrm`.

The `pkgrm` command will give you a list of the install packages; one of those will be the MRBtrans package. Choose its number and verify that that's the package you want to remove; the `pkgrm` program will then remove that package and all its supporting files. You'll be asked if you also want to remove the transmitter's channel directory.

If you used the regular transmitter installation (the one without `pkgadd`) to install the transmitter, you can simply remote the `castanet/transmitter` directory to uninstall the transmitter. You may also want to remove the transmitter's channel directory if you want to remove all traces of the transmitter from your system.

### Getting Help

The documentation for the transmitter is available as a set of HTML Web pages, both on Marimba's Web site and as a channel (called "Transmitter doc" from trans.marimba.com). Choosing any of the Help buttons from the transmitter administration tool will bring up those help files in your browser (on Windows, your default browser will be launched to view the files; on Solaris you'll need to have your browser already running).

### Summary

In this chapter you installed the transmitter and configured it for basic use by a tuner. In the next chapter you'll complete the process: you'll add some channels that then become available to tuners that can access that transmitter.