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.)
As with the installation for the tuner, let's first go through and make sure you've got the ingredients to install everything successfully.
NoteCurrently, 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.
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.
NoteKeep 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.
NoteOn 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.)
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:
NoteThe 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.
NoteIf 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
NoteThe 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.
NoteIf 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.
NoteYou 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
NoteIn 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.
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.
NoteIf 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.
NoteThe 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.
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.
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:
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.
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.
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).
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.