Wowza Streaming Engine VHost.xml configuration reference

The Wowza Streaming Engine™ media server VHost.xml configuration file located at [install-dir]/conf/VHost.xml defines the settings used to configure a virtual host (VHost). Wowza Streaming Engine can serve multiple users from separate virtual hosting environments. Each VHost environment has its own set of configuration files, application folders, and log files. For information about recommended values to use based on server resources, see Tune Wowza Streaming Engine for optimal performance.

A separate VHosts.xml configuration file located at [install-dir]/conf/VHosts.xml lists all of your virtual hosting environments. In VHosts.xml, include a name, configuration path, and connection limit for each virtual host you configure.

Note: The VHost.xml reference applies to the file as installed with the latest version of Wowza Streaming Engine. Some properties described may not apply to the file as installed with earlier versions of Wowza Streaming Engine.

Contents

---

Description
HostPortList
HTTPStreamerAdapters
HandlerThreadPool
TransportThreadPool
IdleWorkers
NetConnections
MediaCasters
LiveStreamTranscoders
HTTPTunnel
Client
RTP
HTTPProvider
WebSocket
Application
StartStartupStreams
Manager
Properties

XML reference

---

Description

A text description of the virtual host environment.

HostPortList

List of IP addresses and TCP ports that Wowza Streaming Engine will bind to for incoming and outgoing streaming connections. Wowza Streaming Engine can be configured for any number of TCP ports.

HostPort - Used to stream RTMP, RTSP, and HTTP. A HostPort can be configured to use Secure Sockets Layer (SSL) and Transport Layer Security (TLS) encryption. HTTP provider configuration is done on a per-HostPort basis.

• Name - A unique name for the host port.
• Type - Specifies how the host port is used: for Streaming or Administration.
• ProcessorCount - Number of threads allocated to use to service connections.
• IpAddress - IP address or domain name of the address that Wowza Streaming Engine will listen to for incoming requests. If IpAddress is set to the wildcard (*) character, the server will try to listen for incoming connections on all available network interfaces.
• Port - A comma-separated list of ports.
• HTTPIdent2Response - Utility class for parsing and converting host-port information from commands. Represents a list of host-port pairs.
• SSLConfig - Secure Sockets Layer (SSL) and Transport Layer Security (TLS) configuration for a given HostPort.
  • KeyStorePath - Full path to the keystore file.
  • KeyStorePassword - Keystore password.
  • KeyStoreType - Keystore type. The default value is JKS for Sun Java JRE.
  • DomainToKeyStoreMapPath - A map of domain names to SSL/TLS certificates.
  • SSLProtocol - Cryptographic protocol. The default value is TLS (Transport Layer Security).
  • Algorithm - Encryption algorithm. The default value is SunX509 for Sun Java JRE.
  • CipherSuites - Comma-separated list of cipher suites.
  • Protocols - Comma-separated list of SSL/TLS protocol names.
  • AllowHttp2 - Boolean for allowing HTTP/2.
• SocketConfiguration - Detailed socket connection configuration that's created by this HostPort definition at runtime. You can use these settings to tune the performance of the socket connections that are used to send data into and out of Wowza Streaming Engine.
  • ReuseAddress - Determines if the address of the outgoing data can be reused.
  • ReceiveBufferSize - Defines the size of the memory buffers that are used when receiving data transfer over the socket connection. A value of 0 for ReceiveBufferSize instructs Wowza Streaming Engine to use the operating system default values for these settings. For operating systems that support it, TCP auto-tuning at the kernel level may be used to set the buffer sizes dynamically for individual connections.
  • ReadBufferSize - Defines the size of the memory buffers that are used when reading data transfer over the socket connection. For operating systems that support it, TCP auto-tuning at the kernel level may be used to set the buffer sizes dynamically for individual connections.
  • SendBufferSize - Defines the size of the memory buffers that are used when sending data transfer over the socket connection. A value of 0 for SendBufferSize instructs Wowza Streaming Engine to use the operating system default values for these settings. For operating systems that support it, TCP auto-tuning at the kernel level may be used to set the buffer sizes dynamically for individual connections.
  • KeepAlive - Time that a connection remains open when no data is being transferred. Set to true (default).
  • TrafficClass - Classification for differentiated service based on priority of traffic on the network.
  • OobInline - Determines if any SSL/TLS urgent data received on the socket is received through the socket input stream. Urgent data is discarded when the option is disabled.
  • SoLingerTime - Determines, in milliseconds, if and for how long a socket waits in order to finish sending pending data after the close function is called on the socket connection.
  • TcpNoDelay - Enables or disables nagling. Nagling is an SSL/TLS feature that combines several small packets into a single, larger packet for more efficient transmission.
  • AcceptorBackLog - Controls the maximum number of TCP connection requests that can be pending before new connection requests are refused. Wowza Streaming Engine will respond to TCP connection requests as quickly as possible. TCP connection requests should not be set to a value of less than 50. Setting this value to -1 allows the operating system to control the maximum number of pending TCP connection requests.

    Note: Using the "automatic" -1 setting value isn't always the best decision. When interpreting a -1 AcceptorBacklog value, some platforms will set a very small number as the maximum possible TCP connection requests and this can greatly increase connection times.

• HTTPStreamerAdapterIDs - Comma-separated list of HTTPStreamers that this HostPort will include when processing HTTP requests. HTTPStreamerAdapterIDs can contain none, one, or more of the following values (separated by commas): cupertinostreaming (HLS), dvrchunkstreaming, mpegdashstreaming.
• HTTPProviders - List of HTTP providers that this HostPort includes when processing HTTP requests. For more information, see Use HTTP providers with the Wowza Streaming Engine Java API.
  • HTTPProvider - A container element for configuring an HTTP provider for the host port.
    • BaseClass - Base class of the HTTPProvider class, such as com.wowza.wms.http.HTTPServerInfoXML.
    • RequestFilters - HTTP request type limiter. To restrict the types of HTTP requests your Web server will process, configure the server to analyze specific criteria for each incoming request as specified by files such as clientaccesspolicy.xml and crossdomain.xml.
    • AuthenticationMethod - Authentication method specifier such as admin-basic, basic, admin-digest, digest, admin-file-digest, block, admin-basic, admin-block, or none.

HTTPStreamerAdapters

List of HTTP Streamers that are enabled for HostPort entries. All HTTP Streamers listed here can be streamed by using the HostPort IP address and port combination. If you want to disable a particular HTTP streaming protocol, you can remove it from this list.

HTTPStreamerAdapter - A container element for configuring HTTP Streamers for the host port.

• ID - Identity that's one of the following options: cupertinostreaming, mpegdashstreaming, tsstreaming, webmstreaming, or dvrchunkstreaming. These options represent the HTTP streaming protocols as well as DVR streaming from origin to edge in a Wowza live stream repeater configuration.
• Name - Name for one of the following options: cupertinostreaming, mpegdashstreaming, tsstreaming, webmstreaming, or dvrchunkstreaming.
• Properties - Custom properties with name, value, and type that can be added by the user for HTTP Streamers.
  • Property - A container element for configuring custom properties.
    • Name - Name of the property.
    • Value - Value of the property as defined by the type.
    • Type - Type of property (Integer, Boolean, or String).

HandlerThreadPool

A container element for configuring the handler thread pool. The handler thread pool is used to process incoming messages.

PoolSize - Maximum size of the virtual host-level threads in the handler pool. If the pool size is set to 0, the server-level handler thread pool is used for this virtual host.

TransportThreadPool

A container element for configuring the transport thread pool. The transport thread pool is used to read/write data from the transport sockets.

PoolSize - Maximum size of the virtual host-level threads in the transport thread pool. If the pool size is set to 0, the server-level transport thread pool is used for this virtual host.

IdleWorkers

A container element for configuring idle events.

WorkerCount - Controls the number of threads being used to generate idle events.

CheckFrequency - The time, in milliseconds, between system checks that monitor if a client has been idle for Client/IdleFrequency. The CheckFrequency value should be one-fourth or less of the Client/IdleFrequency value.

MinimumWaitTime - An interval in seconds that the server will wait.

NetConnections

Settings used to tune connections made between Wowza Streaming Engine servers, for example, when using the live stream repeater.

ProcessorCount - The number of threads allocated to connections.

IdleFrequency - The time, in milliseconds, between server-to-server idle events. A larger idleFrequency decreases load on the server, but increases delay between the time the server publishes the stream and when the client plays it. If you adjust this value, also adjust the IdleWorkers/CheckFrequency to a value that's at least four times smaller. Increasing the IdleFrequency from the default 250 milliseconds will give the CPU a little more time so it won't be working as hard.

SocketConfiguration - A container element for configuring socket connections between servers.

• ReuseAddress - Boolean. This value determines if the address of the incoming RTP datagram can be reused.
• ReceiveBufferSize - Size in bytes of the buffer that receives incoming data. A value of 0 configures Wowza Streaming Engine to use the operating system default values for these settings.
• ReadBufferSize - Size of the memory buffer that contains read data.
• SendBufferSize - Size of the memory buffer that contains data to be sent. A value of 0 configures Wowza Streaming Engine to use the operating system default values for these settings.
• KeepAlive - Time, in milliseconds, that a connection remains open when no data is being transferred.
• TrafficClass - Classification for differentiated service based on priority of traffic on the network.
• OobInline - Determines if any SSL/TLS urgent data received on the socket is received through the socket input stream. Urgent data is discarded when the option is disabled.
• SoLingerTime - Determines, in milliseconds, if and for how long a socket waits in order to finish sending pending data after the close function is called on the socket connection.
• TcpNoDelay - Enables or disables nagling. Nagling is a TCP feature that combines several small packets into a single, larger packet for more efficient transmission.
• AcceptorBackLog - Number of connections allowed in backup queue.

MediaCasters

A container element for configuring source connections with MediaCasters.

ProcessorCount - Number of threads allocated to MediaCasters: ${com.wowza.wms.TuningAuto}.

SocketConfiguration - A container element for configuring socket connection for MediaCasters.

• ReuseAddress - Boolean. This value determines if the address of the incoming RTP datagram can be reused.
• ReceiveBufferSize - Size in bytes of the buffer that receives incoming data. A value of 0 configures Wowza Streaming Engine to use the operating system default values for these settings.
• ReadBufferSize - Size of the memory buffer that contains read data.
• SendBufferSize - Size of the memory buffer that contains data to be sent. A value of 0 configures Wowza Streaming Engine to use the operating system default values for these settings.
• KeepAlive - Time, in milliseconds, that a connection remains open when no data is being transferred.
• TrafficClass - Classification for differentiated service based on priority of traffic on the network.
• OobInline - Determines if any SSL/TLS urgent data received on the socket is received through the socket input stream. Urgent data is discarded when the option is disabled.
• SoLingerTime - Determines, in milliseconds, if and for how long a socket waits in order to finish sending pending data after the close function is called on the socket connection.
• TcpNoDelay - Enables or disables nagling. Nagling is a TCP feature that combines several small packets into a single, larger packet for more efficient transmission.
• ConnectionTimeout - The time (in milliseconds) that this MediaCaster will wait when connecting to a remote service.

LiveStreamTranscoders

A container element for configuring concurrent transcoding of live source streams.

MaximumConcurrentTranscodes - Maximum number of concurrent live source streams that are transcoded at any point in time. This setting is useful if you licensed Wowza Streaming Engine with a license that enables an unlimited number of concurrent transcodes, and you want to limit the number of concurrent transcodes due to CPU/hardware limitations or for billing purposes. A value of 0 allows an unlimited number of concurrent transcodes.

HTTPTunnel

A container element for controlling the keep-alive time.

KeepAliveTimeout - Keepalive time, in milliseconds, for RTMPT, RTMPTE, and RTMPS connections.

Client

A container element for configuring client connection timing.

ClientTimeout - The length of time, in milliseconds, that the server will wait before shutting down an unresponsive client connection.

IdleFrequency - The length of time, in milliseconds, between client idle events.

Note: For basic video on demand (VOD) streaming, a value of 250 for both ClientTimeout and IdleFrequency provides the best reliability-versus-performance ratio. For live streaming, a value between 125 and 250 is more desirable. Higher values will increase the frequency at which media data is sent to clients. If you adjust this value, be sure to also adjust IdleWorkers/CheckFrequency to a value that's less than or equal to one-fourth of this value. For example, if the value of ClientTimeout and IdleFrequency is 200, then the value of IdleWorkers/CheckFrequency should be 50 or less.

RTP

A container element for configuring RTP connections.

IdleFrequency - Time, in milliseconds, between RTP idle events. Idle events are used to send new media data and events to an RTP or MPEG-TS sessions.

DatagramConfiguration - Datagram socket configuration for incoming and outgoing RTP connections.

• Incoming - A container element for configuring the datagram socket for incoming RTP connections.
  • ReuseAddress - Boolean value that determines if the address of the incoming RTP datagram can be reused.
  • ReceiveBufferSize - Size, in bytes, of the incoming UDP buffer.
  • SendBufferSize - Size, in bytes, of the outgoing UDP buffer.
  • MulticastBindToAddress - Determines if the Wowza Streaming Engine instance binds to an address specified by MulticastInterfaceAddress when joining a multicast stream. By default this setting is unused, and the server binds to local network interface.
  • MulticastInterfaceAddress - To force the Wowza Streaming Engine instance to bind to a particular network interface, set MulticastInterfaceAddress to the local address of the network interface that you want Wowza to use when joining the multicast stream.
  • TrafficClass - Inbound classification for differentiated service based on priority of traffic on the network.
  • MulticastTimeout - Timeout value, in milliseconds, for multicast polling.
  • DatagramMaximumPacketSize - Maximum size, in bytes, for a single incoming UDP packet.
• Outgoing - A container element for configuring the datagram socket for outgoing RTP connections.
  • ReuseAddress - Boolean value that determines if the address of the outgoing RTP datagram can be reused.
  • ReceiveBufferSize - Size, in bytes, of the incoming UDP buffer.
  • SendBufferSize - Size, in bytes, of the outgoing UDP buffer.
  • MulticastBindToAddress - Determines if the Wowza Streaming Engine instance binds to an address specified by MulticastInterfaceAddress when joining a multicast stream. By default this setting is unused, and the server binds to the local network interface.
  • MulticastInterfaceAddress - To force the Wowza Streaming Engine instance to bind to a particular network interface, set MulticastInterfaceAddress to the address of the network interface that you want the Wowza Streaming Engine instance to use when joining the multicast stream.
  • TrafficClass - Outbound classification for differentiated service based on priority of traffic on the network.
  • MulticastTimeout - Timeout value, in milliseconds, for multicast polling.
  • DatagramMaximumPacketSize - Maximum size, in bytes, for a single incoming UDP packet.

UnicastIncoming - A container element for configuring incoming unicast UDP streams.

• ProcessorCount - Number of threads allocated to incoming unicast UDP streams.

UnicastOutgoing - A container element for configuring outgoing unicast UDP streams.

• ProcessorCount - Number of threads allocated to outgoing unicast UDP streams.

MulticastIncoming - A container element for configuring incoming multicast UDP streams.

• ProcessorCount - Number of threads allocated to incoming multicast UDP streams.

MulticastOutgoing - A container element for configuring outgoing multicast UDP streams.

• ProcessorCount - Number of threads allocated to outgoing multicast UDP streams.

HTTPProvider

A container element for configuring HTTP provider timing.

KeepAliveTimeout - Time, in milliseconds, that the TCP session is maintained after a response is sent.

EndConnectionTimeout - Time, in milliseconds, that the TCP session validation code waits before a TCP session is terminated because of inactivity.

SlowConnectionBitrate - Estimates the time, in bits-per-second, that it takes to flush data from the TCP send buffer when determining the KeepAliveTimeout time.

IdleFrequency - Time, in milliseconds, between TCP idle events.

WebSocket

A container element for configuring WebSocket connections.

MaximumMessageSize - Maximum size, in bytes, of a single WebSocket message. If any message is larger than this value, the TCP session is terminated to guard against memory run-up. If set to 0, this property isn't used.

PacketFragmentationSize -  Reserved for future use.

MaskOutgoingMessages - Boolean value that determines if outgoing messages are masked. Note that most modern web browsers don't accept masked messages.

IdleFrequency - Time, in milliseconds, between TCP idle events.

ValidationFrequency - Time, in milliseconds, between sending messages from the server to the browser to validate that the TCP session is still active.

MaximumPendingWriteBytes - Maximum number of bytes queued to be written. If this value is exceeded, the TCP session is terminated to guard against memory run-up. If set to 0, this property isn't used.

PingTimeout - Time, in milliseconds, the WebSocket waits for a response to a ping request.

Application

A container element for controlling client connections to applications in your virtual hosting environment.

ApplicationTimeout - Length of time, in milliseconds, that the server will wait before shutting down an application to which no clients are connected. A value of 0 keeps applications running until the virtual host is shut down. If this value isn't provided, the value set in the Application.xml file is used.

PingTimeout - Time, in milliseconds, that the server will wait for a ping response from the client. The ping mechanism that's used to validate a client connection is an RTMP internal ping, not an ICMP ping. If PingTimeout is set to 0, the server will wait indefinitely. If this value isn't provided, the value set in the Application.xml file is used.

UnidentifiedSessionTimeout - Time, in milliseconds, that the server will wait for an unidentified client session before disconnecting the application.

ValidationFrequency - Time, in milliseconds, that the server will wait during server-to-client validation. Validation only occurs if the client stops sending data to the server. Validation is done by sending a ping request from the server to the client. If ValidationFrequency is set to 0, the server won't validate client connections. If this value isn't provided, the value set in the Application.xml file is used.

MaximumPendingWriteBytes - Maximum number of bytes that are allowed to be queued and remain waiting to be sent. If this value is exceeded on an individual client connection, that connection is terminated. If MaximumPendingWriteBytes is set to 0, there is no maximum value.

MaximumSetBufferTime - Maximum buffer time allowed on the client side, in milliseconds. A value for MaximumSetBufferTime of 0 removes the buffer time limit. This property can be used to deter stream rippers that might connect to Wowza Streaming Engine and attempt to set a very large buffer time in order to steal content. Unlimited buffer time can lead to server-side memory run-up.

StartStartupStreams

Boolean value that indicates system action upon startup streams. When set to true, streams that are defined in StartupStreams.xml are instantiated at server startup. When set to false, streams aren't started at server startup.

Manager

A container element for properties that can be defined for use by Wowza Streaming Engine Manager.

TestPlayer - A container element for configuring how to create a URL for test players to connect to Wowza Streaming Engine. You can set up multiple TestPlayer containers to manage the Server options and Secure URL interactions for the Test Playback modal in Wowza Streaming Engine Manager. Check the VHost.xml file for comments detailing this setup.

• IpAddress - IP address or server name the TestPlayer should use to connect to the server. The default value is ${com.wowza.wms.HostPort.IpAddress}. When Wowza StreamLock™ AddOn is configured, IpAddress must be set to the StreamLock certificate name, for example: <IpAddress>52f51948efc92.streamlock.net</IpAddress>.
   

  Note: Amazon EC2 instances use private and public DNS values as IP addresses. EC2 private/public IP address usage with the StreamLock feature requires the private DNS value or the wildcard (*) character to be used as the IP address in order for EC2 AMIs with StreamLock configurations to work. Bind failures occur if the EC2 public DNS value is used as the IP address. You must also restart the server to update StreamLock changes. Restarting the VHost will not update StreamLock changes.

• Port - Port that the TestPlayer should use to connect to the server. The default value is ${com.wowza.wms.HostPort.FirstStreamingPort}. If a nonstandard SSL/TLS port is used, set it explicitly to the port, for example, <Port>9443</Port>. If you have enabled StreamLock for the default streaming port (1935), keep the default Port value. When multiple streaming ports are defined for a VHost, the default port ${com.wowza.wms.HostPort.FirstStreamingPort} can be overridden.
• SSLEnable - Enables the test player to use a VHost port with SSL/TLS enabled. Sets the stream URL protocol to https, rtmps, or rtsps. The default value is ${com.wowza.wms.HostPort.SSLEnable}, which will query the hostport in VHost.xml and set to true or false depending on its value. The true/false values for SSLEnable determine which URL prefix is used in test player URLs –true (rtmps, rtsps, or https) or false (rtmp, rtsp, or http).

Properties - Custom properties with name, value, and type that the user can add for Wowza Streaming Engine Manager.

• Property - A container element for configuring custom properties.
  • Name - Name of the property.
  • Value - Value of the property as defined by the type.
  • Type - Type of property (Integer, Boolean, or String).

Properties

Custom properties with name, value, and type that can be added by the user for the virtual host. All virtual host properties are copied to virtual hosts upon creation. These properties are available in the Java API through the IVHost.getProperties() interface.

Property - A container element for configuring custom properties.

• Name - Name of the property.
• Value - Value of the property as defined by the type.
• Type - Type of property (Integer, Boolean, or String).