Chapter 13: ISP Hosting

ISP Hosting features provide a way to allot connections to users. If you are an Internet Service Provider (ISP), you can host streaming media on behalf of your customers.

ISP Hosting Features

RealServer works with your existing user accounts and user directory structure to make users' media files available for streaming. You allocate a minimum and maximum number of connections for each account, based on the number of streams present in your license.

Reserve and Limit Connections for Each User Account
Set aside connections or give a maximum number. Allocating on a per-connection basis, rather than by stream, ensures that SMIL files which reference multiple streams will always be served.
Store User Account Information in Separate Files
User account information is stored in a text file, which lists pathing and stream information. List all user account information in a single file, or use separate files to make management easier.
Customize User Account Information
Within the user list file, create customized account path and stream information. Or, create a single entry that applies to all user accounts.
Use File System Mount Points
Take advantage of the RealServer G2 file system to store users' content in any directory, in any location.
Preserve User Lists from Previous Versions of RealServer
If you used a previous version of RealServer to host content, use your existing user account information with a minimum of changes.

Overview

There are four components of the ISP hosting feature:

User list files, which describe the user account structure, and stream settings available to each account.
The RealServer configuration file, which gives the actual location of the users' media files.
Directories where the media files are stored.
URLs, used by RealPlayer, that point to the media files.

The ISP Hosting feature is configured by editing the configuration file directly, and by creating a text file which lists the account names.

Features Available to Hosted Customers

Users inherit most features configured on your RealServer: hosting of on-demand content, and access control are available.

Splitting, authentication of ISP hosting users' content, broadcasting live content, and multicasting are not available for hosted material.

Tracking Account Usage

Media files which have been served are recorded in the access log. The fourth field in each record of the access log, identified by the GET statement, lists the path and filename of each clip served. Compare this information to the path information you've set up to determine how many clips have been streamed from each account.

Compatibility with Previous Versions of RealServer

If you used ISP Hosting in RealServer versions 3.0 through 5.0, you can still use the UserList from your previous configuration file. Refer to "Creating User Lists From Earlier Versions" for instructions on how to copy it into a new text file and reformat it.

Previous versions of RealServer listed minimum and maximum settings for the number of streams available to each account. In RealServer G2 6.1, those settings now refer to the number of connections available to each account. This allows customers to serve SMIL files-which may reference several streams simultaneously-without running out of streams.

Previous editions of RealServer Administration Guide described two methods of referring to account structures, called "Naming Convention One" and "Naming Convention Two." In this manual, those are renamed "method one" and "method two" respectively.

User Accounts

When RealServer receives a request for streaming media, it looks at user account information to determine which user is hosting the requested content.

Account information is stored in user list files. You can create a separate account name for each user, or just set up a generic account that applies to all users.

Each account has three pieces of information associated with it:

Account name
Path where the account's files will be stored
Minimum and maximum connections available to the account

Account Names

There are two methods of identifying account names and settings. The method you choose depends on your existing directory structure (or on the directory structure you plan to create). Choose the account naming method that best matches your directory structure.

You can create the accounts individually, or set up a generic method that will apply to all users. This section describes the options for user account structures.

Regardless of which method you choose, you will create a text file, called a user list, that lists the user names and account information. In method one, the user list can contain information about individual accounts. Method two only gives one way of specifying user account information.

Warning
Method two is suitable only for RealServers dedicated exclusively to serving content for ISP-type customers. If you use method two, content can only be served from user accounts.

	Warning
Method two is suitable only for RealServers dedicated exclusively to serving content for ISP-type customers. If you use method two, content can only be served from user accounts.

If your user accounts are set up according to a strict directory hierarchy, such as an alphabetical organization, Method Two is the most suitable. For example,

You can create multiple files with lists of user names in them, but you cannot combine methods one and two. You must choose a single method.

Comparison of Naming Methods
Method One	Method Two
Works with any directory structure.	Works with a hierarchical directory structure, especially an alphabetic one. For example: `/UserAccounts/s/sa /UserAccounts/s/sb /UserAccounts/s/sc`
Some users have customized settings, while generic settings describe all other users.	All users have identical settings.
RealServer can host content for users and ordinary content as well.	RealServer can only host content from user accounts.

Paths to Users' Content

This section describes how RealServer processes all requests when ISP Hosting is in use. Four items control where RealServer looks for hosted media:

RealServer compares the path in the URL to the /path/ information in the user lists. The path information matches the UserPath variable in the configuration file. This is not a physical path; it is used only for the next step, and serves as a way to group user account names logically.
If your user list contains individual account names, RealServer searches these to find a match. If it doesn't find an exact match, it uses the generic account's path information.

If you are using Method Two, it uses the generic account's path information.
Using the /path/ information, RealServer goes to the ISPHosting list of the configuration file, where it looks within the TranslationMounts list for a matching UserPath. Once it finds a match (it looks for the longest possible match), RealServer records the MountPoint located within the same list. This translates the logical path to a file system.
Next, RealServer looks in the FSMount list for a file system whose mount point matches the MountPoint from the ISPHosting list. Once it finds the correct mount point, RealServer notes the associated BasePath.
The media will be in a directory relative to BasePath.

Typically, users' content is mapped to a special ISP hosting mount point and base path. User directories are located under the base path.

Number of Connections Available for Each Account

Each account has a reserved number of connections and a maximum number of connections associated with it. The reserved setting guarantees that this number of connections will always be available to clients that attempt to view a particular user's hosted media. For generically-named accounts (using method two, and the generic ~* structure in method one), minimum connections are not activated until content is played from that user's account. However, if account names are listed individually, the minimum connections will be reserved as soon as RealServer starts.

Tip
To guarantee that connections will always be available for certain customers, list their account names in the user file, rather than using a generic scheme.

	Tip
To guarantee that connections will always be available for certain customers, list their account names in the user file, rather than using a generic scheme.

The maximum setting refers to the highest number of connections that will be available for a particular customer's content. Anyone who tries to watch a clip after that account's maximum number of connections are in use will receive an error message, even if connections are available to other accounts.

Setting Up ISP Hosting

The steps for setting up ISP hosting are the following:

Create the user list file.
This file establishes account information.

Additional Information
See "Creating the User List".
Set up the configuration file.
The configuration file indicates where to find the user lists, and completes the pathing information needed to located the users' media.

Additional Information
See "Setting Up the Configuration File".
Placing files in the correct locations and creating URLs for the customers' content.

Additional Information
Refer to "Storing Customer Files and Creating URLs for Users' Content".

	Additional Information
See "Creating the User List".

	Additional Information
See "Setting Up the Configuration File".

	Additional Information
Refer to "Storing Customer Files and Creating URLs for Users' Content".

Creating the User List

Create the user list, and store it anywhere that is accessible to RealServer.

The user list is a text file with the following format:

UserList [ {method, /path/, connections_reserved, connections_limit}

]

where:

method is the type of method you're using:

Method one-substitute a specific user name and create a separate entry for each user, or type ~* to indicate that all accounts will be the same. See "Method One" for more information.
Method two-type *n, where n is the number of directories after which individual user directories appear, relative to BasePath. See "Method Two" for more information.

/path/ indicates the path to the users' content. This is the chief difference between the account naming methods-whether the path is based on the user's account name or on a hierarchical directory structure. For both methods, see "Paths to Users' Content" to see how the actual path to users' content is determined.

connections_reserved is the minimum number of connections reserved for this user. 0 indicates that no connections are reserved. See "Number of Connections Available for Each Account" for more information.

connections_limit is the maximum number of connections available to this user. 0 indicates that no connections may be used. See "Number of Connections Available for Each Account" for more information.

Tip
You can include comments in the file by preceding a line with a semi-colon (;).

	Tip
You can include comments in the file by preceding a line with a semi-colon (;).

Using Multiple User List Files

You can create as many user lists as you want; using multiple files can make administration easier. For example, an ISP provider for a three-state area might put commercial accounts in one file and personal accounts in another file.

Note
RealServer loads the user lists in the order they appear in the configuration file; if the same user name appears in more than one list, RealServer uses the settings in the last user list.

	Note
RealServer loads the user lists in the order they appear in the configuration file; if the same user name appears in more than one list, RealServer uses the settings in the last user list.

Method One URLs and Options

URLs in Method One have the following format:

rtsp://server.company.com:554/~username/directory/filename

There are two ways of creating the user list entry. You can list individual accounts specifically:

UserList [ {username1, /path/, connections_reserved, connections_limit} {username2, /path/, connections_reserved, connections_limit} {username3, /path/, connections_reserved, connections_limit} ]

If you have a large number of accounts to create, and they will all use the same number of connections, create a single entry that refers to all accounts generically:

UserList [ {~*, /path/, connections_reserved, connections_limit} ]

These can be combined in a single user list. Combining them is convenient if most users have the same settings, but a few have different number of connections reserved, or use different paths:

In the following example, customized accounts for four users have been created, and all other accounts will use the default settings shown in the last entry:


UserList [
{chris, /users/chris/media/, 2, 5}, 
{lee, /users/lee/speeches/streams/, 0, 100}, 
{sandy, /users/sandy/ra/, 2, 50}, 
{pat, /users/pat/ra/, 1, 35} 
{~*, /users/, 1, 35} 
]

Method Two URLs and Options

URLs created with this method have the following format:

rtsp://server.company.com:554/directory1/directory2/directory3/filename

For example, rtsp://server.company.com:554/users/s/sa/sandy/band.rm

There is only one user list entry, which applies to all users, and it has the following format:

UserList [ {*n, /path/, connections_reserved, connections_limit}

]

Creating User Lists From Earlier Versions

Recycle your UserList entry from the configuration file of previous versions. If your UserList is long, you may want to create more than one file. Refer to "Using Multiple User List Files".

After you create the new user list file, follow the instructions in "Setting Up the Configuration File".

To create a user list from existing settings:

Open your old configuration file.
Locate the UserList entry.
Copy and paste the existing UserList setting into a new text file.
Reformat the file so that it matches the new format by moving each item onto a separate line:
- UserList and the opening square bracket ([) go on the first line.
- Information about each account is enclosed within curly brackets ({ and }). Place each account on a separate line.
- The file ends with a closing square bracket (]) on the last line.
  Use the following format:
```
UserList [
{method, /path/, min, max}
]
```
  For example, the following entry:
```
UserList [ {ElectroMotors, /usr/elector/ra, 2, 5}, {CityWeld, /usr/cityweld/ra, 1, 3}]
```
  should now look like this:
```
UserList [ 
{ElectroMotors, /usr/elector/ra, 2, 5}, 
{CityWeld, /usr/cityweld/ra, 1, 3}
]
```

Setting Up the Configuration File

For instructions on editing the configuration file, refer to Appendix A: Configuration File Syntax and "Editing the Configuration File with a Text Editor" in Chapter 4 before beginning.

Within the configuration file, you will customize three lists:

UserLists-connects the user accounts with UserPath variables.
TranslationMounts-associates UserPath variable with a file system.
FSMount-associates file system with locations of user directories and their content.

Add the following to the configuration file (generic settings are shown-you will need to customize this list):

<List Name="ISPHosting"> <List Name="TranslationMounts"> <List Name="List 1"> <Var MountPoint="/mountpoint/"/> <Var UserPath="/userpath/"/> </List> </List> <List Name="UserLists"> <Var File1="userlist1"/> <Var File2="userlist2"/> </List> </List>

To set up the UserLists list:

Within the ISPHosting list, the UserFiles list indicates where to find the user lists.

If you have only one user list, create a single entry.

<List Name="UserLists"><Var File="c:\accounts\customers.txt"/> </List>

If you have multiple lists, create multiple file variables (each variable needs a unique name):

<List Name="UserLists"><Var File1="c:\accounts\commercial\local.txt"/> <Var File2="c:\accounts\commercial\remote.txt"/> <Var File3="c:\accounts\personal\local.txt"/> </List>

To set up the TranslationMounts list:

In the TranslationMounts list of the ISPHosting list, create a list for each value of path in the user files. Each list contains two variables: UserPath, which matches the value of path in the user files, and MountPoint, which indicates which file system to use in the FSMount list.

If you set up explicit user accounts (using method one), create a separate list (List1, List2, and so on) for each unique user path.

<List Name="ISPHosting"> ... <List Name="TranslationMounts"> <List Name="List 1">
<Var MountPoint="/accounts/"/> <Var UserPath="/users/"/></List> ... </List>

To set up the FSMount list:

In the FSMount list, create a file system list for the ISP files. Use the same value for MountPoint as you did in the TranslationMounts list.

<List Name="FSMount">

...other mount points...

  <List Name="ISP">
    <Var ShortName="pn-local"/>

    <Var MountPoint="/accounts/"/>
    <Var BasePath="C:\UserAccounts"/>

  </List>

...other mount points...

</List>

Storing Customer Files and Creating URLs for Users' Content

Locating Media Files

Customers' media files are stored in their directories.

Building URLs

An URL to hosted content depends on the format of the user list file.

Method One

When method one is in use, the URL always includes a tilde (~) and the account name.


rtsp://server.company.com/~username/filename.rm

RealServer will look for a directory named username under the appropriate base path.

Method Two

In method two, the URL always lists the path to the user directory, relative to the base path. The number of directories in the URL is the same as the number given in the user list file.

Examples

The examples below use the following values for the user list and configuration file:.


`/path/`in user list, `UserPath` in `TranslationMounts`	/users/
`MountPoint` in `TranslationMounts` and `FSMount` lists	`/accounts/`
`BasePath` in the `FSMount` list	`C:\UserAccounts`

Method One

With the following user file as an example:

UserList [ {~*, /users/, 2, 25} ]

and the following sample location for users' content:

C:\UserAccounts\Sandy

The URL would have the following format:


rtsp://server.company.com/~username/filename.rm

If the user had created a subdirectory in her account:

C:\UserAccounts\Sandy\media

it would be included in the URL:


rtsp://server.company.com/~sandy/media/filename.rm

Method Two

With the following user file as an example:

UserList [ {*3, /users/, 2, 25} ]

and the following sample location for users' content:


C:\UserAccounts\s\sa\sandy

The URL would have the following format:


rtsp://server.company.com/s/sa/sandy/filename.rm

If the user had created a subdirectory in his account:


C:\UserAccounts\s\sa\sandy\media

It would be included in the URL:


rtsp://server.company.com/s/sa/sandy/media/filename.rm

Additional Considerations

Here are some additional factors to keep in mind as you configure RealServer to host content for your customers.

Providing Access to Users
To allow customers to be able to place their media files on your RealServer, you will need to provide them access rights to the file server.
Port Numbers
If you change the port numbers for RTSP Port, PNA Port and HTTP Port from their default values, you will need to tell your users so that they can include the new ports in their URLs. (If an URL does not include a port number, the client uses default values for contacting the RealServer. But if the RealServer is no longer listening on those ports, it will not receive the request.) See "Port Variables" for more information.