previous next

Appendix E: RealServer Configuration

The RealServer configuration file resides in the same directory as the RealServer executable. This file contains predefined parameters that determine how RealServer operates. It can also contain custom parameters for use by any system plug-in. When it starts up, RealServer loads the configuration file into its registry. Plug-ins can then access the configuration parameters through the registry.

Additional Information
See "Appendix F: RealServer Property Registry".

The configuration file is formatted with XML tags. Formatting the file with XML eliminates the need for hard-coded variables and lets the configuration file support arbitrarily complex custom variables. You can edit the configuration file with a text editor or any XML editing tool.

The following sections explain the configuration file syntax, which you need to understand to create custom properties. They then explain several of the predefined RealServer properties, which you need to set correctly for RealServer to operate. Be sure to restart RealServer after editing the configuration file.

Additional Information
Get full information on the configuration file from RealServer Administration Guide available at http://service.real.com/help/library/servers.html.

Note
If you plan to create complex variables, be sure that you first understand the rules for "well-formed" XML. To learn more about XML, visit http://www.w3.org/XML.

Configuration File Syntax

The RealServer configuration file should begin with the following tag, which identifies the file as XML:


<?XML Version="1.0" ?> 

If you are familiar with XML, you will notice that the configuration file does not include a DTD (Document Type Definition). This means it must conform to the rules for a "well-formed" XML file. The end of the file does not require an end tag similar to the </HTML> tag.

As with HTML, you can add comments to an XML file with this tag:


<!-- Comment --> 

Name/Value Pair Syntax

Most configuration parameters are name/value pairs indicated by a <Var/> tag:


<Var parameter_name="parameter_value"/> 

For example:


<Var MaxConnections="100"/> 

Note some important restrictions with XML. First, an XML tag such as <Var> that does not have a corresponding end tag must itself end with a forward slash ("/"). Second, attribute values must be in double quotes. Finally, you cannot use Name or Value as a parameter name or value.

List Syntax

You can configure complex parameters in a list that comprises a beginning <List> tag, an ending </List> tag, and any number of <Var> tags within it. As in HTML, you can also nest lists within lists. The <List> tag must provide a list name in the form:


<List Name="list_name"> 

The following is an example of list syntax using the FSMount parameter:


<List Name="FSMount">
<List Name="pn-live3">
<Var MountPoint="/live/"/>
<Var Port="7090"/>
</List>
<List Name="pn-local">
<Var MountPoint="/"/>
<Var BasePath="/home/media/rafiles"/>
<Var Authentication="True"/>
</List>
</List>

Additional Information
See "Appendix F: RealServer Property Registry" for more information on retrieving named or unnamed variables from the RealServer registry.

Case and Datatypes

License Parameters

The following configuration parameters set RealServer's basic licensing information.

CustomerName

For this parameter value, paste in the customer name you received in your email response after downloading the RealSystem SDK. For example:


<Var CustomerName="RMATestKey"/> 

LicenseKey

For this parameter value, paste in the license key you received in your email response after downloading the RealSystem SDK.

MaxConnections

This optional parameter sets the maximum number of client connections allowed by RealServer. The absolute maximum is controlled by the RealServer license key. Use this parameter if you want to set a maximum that is less than that allowed by the license. For example:


<Var MaxConnections="20"/>

Path Parameters

Several configuration file parameters specify paths and file names used by RealServer to locate resources. Paths can be absolute or relative to the directory that contains the RealServer executable. A blank value specifies the directory that contains the RealServer executable. Make sure that the directories exist before you start RealServer. RealServer creates the files you specify, however.

ErrorLogPath

For this variable, enter the path and name of the file that will hold the RealServer error log. For example:


<Var ErrorLogPath="/home/media/rmlogs/rmserver.error"/> 

LogPath

Specify for LogPath the path and name of the file that will hold the RealServer access logs. For example:


<Var LogPath="/home/media/rmlogs/rmserver.access"/> 

PidPath

Enter for PidPath the path and name of the file that will hold the RealServer process ID logs. For example:


<Var PidPath="/home/media/rmlogs/rmserver.pid"/> 

PluginDirectory

For PluginDirectory, specify the directory that holds the RealServer plug-ins. The default value specifies the directory that contains the RealServer executable. You can change this, for example, to a subdirectory:


<Var PluginDirectory="plugins"/> 

Port Parameters

The following parameters affect how RealServer uses the server machine ports.

Machine Port Parameters
Parameter Supported Protocol Default Port
RTSPPort RTSP 554
PNAPort PNA 7070
HTTPPort HTTP 8080

You can change these defaults by specifying a new value with the RTSPPort, PNAPort, or HTTPPort configuration parameter, respectively. For example:


<Var RTSPPort="6090"/> 

Note
Currently RealServer supports all three protocols on all three ports. If you define the RTSP port as 6090, for example, RealServer also accepts PNA and HTTP connections on that port.

IPBindings

The optional IPBindings parameter specifies one or more IP addresses or Web addresses that are bound to the protocol ports. For example, the following parameter:


<List Name="IPBindings">
<Var Address="127.0.0.1"/>
<Var Address="darmok.dev.real.com"/>
</List>

specifies that URLs containing the address 127.0.0.1 or darmok.dev.real.com use only the protocol ports described above.

Warning
If you do not bind any addresses, do not include the IPBindings parameter in the configuration file. System errors may occur if you put this tag in the file without defining any addresses.

Server Monitor Parameters

The MonitorPassword and MonitorPort parameters allow a monitoring interface (such as the Java Performance Monitor) to connect to RealServer. MonitorPort defines the server port the interface connects to. MonitorPassword defines the password the interface must supply. Here is an example:


<Var MonitorPassword="baroque27"/> 
<Var MonitorPort="9090"/>

MimeTypes Parameter

Include the MimeTypes parameter if you plan to deliver content from RealServer through HTTP streaming. This parameter, which is not necessary if all RealServer connections use RTSP or PNA, assigns file extensions to stream MIME types. Here is an example:


<List Name="MimeTypes">
<List Name="application/x-pn-realaudio">
<Var Ext="ra"/>
<Var Ext="ram"/>
</List>
</List>

FSMount Parameter

The FSMount parameter determines which file system plug-in or broadcast plug-in RealServer uses to locate a file or live broadcast for a URL request. The parameter has the following syntax:


<List Name="FSMount">
<List Name="plugin_short_name">
<Var Variable="value"/>
.
.
.
</List>
.
.
.
</List>

Plug-in Short Name

The plug-in short name is encoded in the plug-in. For example, the plug-in designed to serve files from RealServer's local disks has the short name pn-local.

Additional Information
See "Chapter 2: SDK Organization" for the locations and short names of the file system and broadcast plug-ins shipped with RealServer.

MountPoint and BasePath

A MountPoint variable is required for all plug-in list elements. It describes a URL mount point, which precedes the file name and ends with a slash (/). When RealServer receives a URL request, it uses the mount point to determine which plug-in to use. The BasePath variable identifies the root directory for content files served by the plug-in. Its value can be absolute or relative to the directory that holds the RealServer executable. The following sections provide examples of these variables.

Multiple Mount Points for a Plug-In

You can define any number of mount points for each file system plug-in. You simply add a plug-in entry for each mount point. Because of uniqueness requirements, subsequent plug-in entries for the same plug-in use a unique, arbitrary plug-in value and define the plug-in's actual short name as a variable. For example, the following indicates that the local file system plug-in serves URL requests coming in on the mount points / and media/. Note that the separate plug-in entries allow the plug-in to serve from different base paths:


<List Name="FSMount">
<List Name="pn-local">
<Var MountPoint="/"/>
<Var BasePath="/home/rmfiles"/>
</List>
<List Name="pn-local-2">
<Var MountPoint="/media/"/>
<Var BasePath="/media/rmfiles"/>
<Var ShortName="pn-local"/>
</List>
</List>

Multiple Plug-Ins for a Mount Point

Any number of file system plug-ins can serve the same mount point. When a request comes in on a mount point served by several plug-ins, RealServer starts with the first plug-in defined for that mount point in the FSMount list. If it doesn't find the file on that plug-in's file system, it checks the next plug-in that serves the mount point. This repeats until RealServer either finds the file or exhausts all plug-ins defined for that mount point and generates an error message.

URL Redirection

You can also use the FSMount parameter to redirect connections. For example, RealServer includes an HTTP file system plug-in that lets RealServer stream a file served off a Web server. You would define for this plug-in the mount point /http/ as shown here:


<List Name="FSMount">
<List Name="pn-http">
<Var MountPoint="/http/"/>
</List>
</List>

RealServer interprets the mount point as a URL request beginning with http://. So a URL such as:


rtsp://www.real.com/http/www.myserver.com/music.ra 

causes RealServer to connect to http://www.myserver.com through its HTTP file system plug-in and stream music.ra as it is served by that Web server.

Authentication

The local file system plug-in (pn-local) accepts an Authentication variable to turn on file authentication:


<List Name="FSMount">
<List Name="pn-local">
<Var MountPoint="/"/>
<Var BasePath="/home/rmfiles"/>
<Var Authentication="True"/>
</List>
</List>

Note
How a third-party file system plug-in turns on file authentication is a detail of its implementation. RealServer passes a file system plug-in its FSMount parameters during initialization. The plug-in may therefore use the same Authentication variable as the pn-local plug-in. However, the XML-based configuration file supports the inclusion of any custom parameters in an FSMount variable.

Additional Information
See "Authentication Parameters".

Port and Password

The plug-in entry for a broadcast plug-in or an encoder application that uses a RealSystem remote broadcasting feature takes a Port variable and, optionally, a Password variable. The Port variable defines the server port the live stream comes in on. The Password value determines which password the broadcast application must send RealServer to connect. If you do not specify a password, any application can connect.

Suppose you use the RealSystem default broadcast plug-in (short name: pn-encoder) to serve requests with a /live/ mount point:


rtsp://real.com/live/newnews.rm 

If the broadcast application connects to port 7072 and uses the password hobart324, you would add the following plug-in entry to the FSMount list:


<List Name="FSMount">
<List Name="pn-encoder">
<Var MountPoint="/live/"/>
<Var Port="7072"/>
<Var Password="hobart324"/>
</List>
</List>

Authentication Parameters

Set the following parameters if you use authentication. For file authentication through the local file system plug-in (pn-local), set that plug-in's Authentication variable in FSMount.

Additional Information
For more on the FSMount Authentication variable, see "Authentication". See also "Chapter 19: Authentication".

HTTPAuthType

For authentication on URL requests, specify for HTTPAuthType a value of 1 to use basic authorization, or a value of 2 to use DIGEST authentication for HTTP connections. (RTSP connections always use DIGEST authorization.) The default is basic authentication, so you can turn on DIGEST authentication by specifying the following in the configuration file:


<Var HTTPAuthType="2"/> 

Note
A file object can override this setting on a case-by-case basis to determine which type of authorization to use for an HTTP connection. See "Example 1: File System Plug-In" for more information.

Realm

If you use DIGEST authentication over RTSP or HTTP connections, you need to specify a Realm such as the following:


<Var Realm="darmok.dev.real.com"/> 

PasswordFile

For this parameter, enter the path and name of the password file that holds the usernames and passwords for authentication. The path can be absolute or relative to the directory that contains the RealServer executable. Make sure that the directory and file exist before you use the authentication feature. Here is an example:


<Var PasswordFile="/home/media/.rmpasswords"/> 

Configuration File Example

The following is a sample configuration file meant to illustrate the file syntax. Your configuration file will differ depending on your system options and set-up. The order of the parameters in the file does not matter.


<?XML Version="1.0" ?>

<!-- Please read the configuration section of the manual -->
<!-- before adding any new entries to this file. -->

<!-- P A T H S -->
<Var LogPath="C:\Program Files\Real\RealServer\Logs\rmaccess.log"/>
<Var ErrorLogPath="C:\Program Files\Real\RealServer\Logs\rmerror.log"/>
<Var PidPath="C:\Program Files\Real\RealServer\Logs\rmserver.pid"/>
<Var PluginDirectory="C:\Program Files\Real\RealServer\Plugins"/>
<Var SupportPluginDirectory="C:\Program Files\Real\RealServer\Lib"/>
<Var LicenseDirectory="C:\Program Files\Real\RealServer\License"/>

<!-- P O R T S -->
<!--UNIX customers must have root privileges to execute the server -->
<!--with the RTSP port set to 554. -->
<!--The following are the default ports that RealPlayer and -->
<!--RealPlayer Plus clients will connect to for an URL that has -->
<!--no port specified: -->
<!-- RTSP: 554 -->
<!-- PNM: 7070 -->
<!-- HTTP: 80 (...then 8080 if 80 is unavailable) -->
<Var RTSPPort="554"/>
<Var PNAPort="7070"/>
<Var HTTPPort="8080"/>
<Var MonitorPort="9090"/>
<Var AdminPort="7822"/>

<!-- P A S S W O R D S -->
<Var MonitorPassword="letmein"/>

<!-- A L L O W A N C E -->
<Var ValidPlayersOnly="True"/>

<!-- L O G G I N G -->
<Var LoggingStyle="5"/>
<Var StatsMask="3"/>

<!-- L I V E A R C H I V I N G -->
<List Name="LiveArchive">
<List Name="*">
<Var TargetDirectory="/Archive/"/>
<Var BandwidthNegotiation="True"/>
<Var FileSize="0"/>
<Var FileTime="0m0h0d"/>
<Var NoArchive="True"/>
</List>
</List>

<!-- H T T P S U P P O R T -->
<List Name="HTTPDeliverable">
<Var Path_0="/admin"/>
<Var Path_1="/localadminfs"/>
<Var Path_2="/ramgen"/>
<Var Path_3="/farm"/>
</List>

<!-- M I M E T Y P E S -->
<List Name="MimeTypes">
<List Name="text/html">
<Var Ext_1="html"/>
<Var Ext_2="htm"/>
</List>
<List Name="audio/x-pn-realaudio">
<Var Ext_1="ram"/>
</List>
<List Name="image/gif">
<Var Ext_1="gif"/>
</List>
<List Name="image/jpg">
<Var Ext_1="jpg"/>
<Var Ext_2="jpeg"/>
</List>
</List>

<!-- A U T H E N T I C A T I O N -->
<List Name="AuthenticationRealms">
<List Name="SecureAdmin">
<Var Realm="realserver.company.com.AdminRealm"/>
<List Name="BasicAuthenticator">
<Var PluginID="rn-auth-basic"/>
<Var DatabaseID="Admin_Basic"/>
</List>
</List>
<List Name="SecureEncoder">
<Var Realm="realserver.company.com.EncoderRealm"/>
<List Name="RN5Authenticator">
<Var PluginID="rn-auth-rn5"/>
<Var DatabaseID="Encoder_RN5"/>
</List>
</List>
<List Name="SecureContent">
<Var Realm="realserver.company.com.ContentRealm"/>
<List Name="RN5Authenticator">
<Var PluginID="rn-auth-rn5"/>
<Var DatabaseID="Content_RN5"/>
</List>
</List>
</List>

<!-- C O M M E R C E -->
<List Name="CommerceRules">
<List Name="SecureUserContent">
<Var ProtectedVirtualPath="/secure"/>
<Var Realm="realserver.company.com.ContentRealm"/>
<!-- <Var UseGUIDValidation="True"/ -->
<Var EvaluatePermissions="True"/>
<Var DatabaseID="Content_RN5"/>
<!-- <Var AllowDuplicateIDs="True"/ -->
</List>
<List Name="SecureG2LiveContent">
<Var ProtectedVirtualPath="/encoder/secure"/>
<Var Realm="realserver.company.com.ContentRealm"/>
<!-- <Var UseGUIDValidation="True"/ -->
<Var EvaluatePermissions="True"/>
<Var DatabaseID="Content_RN5"/>
<!-- <Var AllowDuplicateIDs="True"/ -->
</List>
<List Name="SecurePreG2LiveContent">
<Var ProtectedVirtualPath="/live/secure"/>
<Var Realm="realserver.company.com.ContentRealm"/>
<!-- <Var UseGUIDValidation="True"/ -->
<Var EvaluatePermissions="True"/>
<Var DatabaseID="Content_RN5"/>
<!-- <Var AllowDuplicateIDs="True"/ -->
</List>
<List Name="SecurePlayerContent">
<Var ProtectedVirtualPath="/secure/player"/>
<Var UseGUIDValidation="True"/>
<Var EvaluatePermissions="True"/>
<Var DatabaseID="PlayerContent"/>
<!-- <Var AllowDuplicateIDs="True"/ -->
</List>
</List>

<List Name="GUIDRegistrationPrefixes">
<List Name="PlayerContentRegistration">
<Var GUIDRegistrationPrefix="register"/>
<Var DatabaseID="PlayerContent"/>
</List>
</List>

<!-- D A T A B A S E S -->
<List Name="Databases">
<List Name="Admin_Basic">
<Var PluginID="rn-db-wrapper"/>
<Var PathToDBPlugin="C:\Program Files\Real\RealServer\Plugins\ppvb3260.dll"/>
<Var DBName="C:\Program Files\Real\RealServer\adm_b_db"/>
</List>
<List Name="Encoder_RN5">
<Var PluginID="rn-db-wrapper"/>
<Var PathToDBPlugin="C:\Program Files\Real\RealServer\Plugins\ppvb3260.dll"/>
<Var DBName="C:\Program Files\Real\RealServer\enc_r_db"/>
</List>
<List Name="Content_RN5">
<Var PluginID="rn-db-wrapper"/>
<Var PathToDBPlugin="C:\Program Files\Real\RealServer\Plugins\ppvb3260.dll"/>
<Var DBName="C:\Program Files\Real\RealServer\con_r_db"/>
</List>
<List Name="PlayerContent">
<Var PluginID="rn-db-wrapper"/>
<Var PathToDBPlugin="C:\Program Files\Real\RealServer\Plugins\ppvb3260.dll"/>
<Var DBName="C:\Program Files\Real\RealServer\con_p_db"/>
</List>
</List>

<!-- F I L E S Y S T E M S -->
<!-- ---------------------- -->
<List Name="FSMount">
<!-- Local File System; Media -->
<List Name="RealSystem Content">
<Var ShortName="pn-local"/>
<Var MountPoint="/"/>
<Var BasePath="C:\Program Files\Real\RealServer\Content"/>
</List>
<!-- Local File System; Secure Media -->
<List Name="RealSystem Secure Content">
<Var ShortName="pn-local"/>
<Var MountPoint="/secure/"/>
<Var BasePath="C:\Program Files\Real\RealServer\Secure"/>
</List>
<!-- Local File System; HTML -->
<List Name="RealSystem Administrator">
<Var ShortName="pn-local"/>
<Var MountPoint="/localadminfs/"/>
<Var BasePath="C:\Program Files\Real\RealServer\RealAdministrator"/>
</List>
<!-- Admin File System -->
<List Name="RealSystem Administrator Files">
<Var ShortName="pn-admin"/>
<Var MountPoint="/admin/"/>
<Var Authentication="True"/>
<Var BaseMountPoint="/localadminfs/"/>
<Var Realm="realserver.company.com.AdminRealm"/>
</List>
<!-- G2 Encoders -->
<List Name="RealSystem G2 Encoders">
<Var ShortName="pn-encoder"/>
<Var MountPoint="/encoder/"/>
<Var Port="4040"/>
<Var EncoderRealm="realserver.company.com.EncoderRealm"/>
</List>
<!-- Pre-G2 Encoders -->
<List Name="Pre-RealSystem G2 Encoders">
<Var ShortName="pn-live3"/>
<Var MountPoint="/live/"/>
<Var Port="5050"/>
<!-- Var Password="letmein"/ -->
</List>
<!-- RAM File Generator -->
<List Name="RAM File Generator">
<Var ShortName="pn-ramgen"/>
<Var MountPoint="/ramgen/"/>
</List>
</List>

<!-- C A C H I N G -->
<Var TSPort="7802"/>
<Var TSEnable="1"/>
<Var TSLog="1"/>
<Var TSLogPath="C:\Program Files\Real\RealServer\Logs\cache.log"/>


Copyright © 2000 RealNetworks
For technical support, please contact supportsdk@real.com.
This file last updated on 05/17/00 at 12:50:44.
previous next