Documentation

The manual page xbmsd(8) is provided here for convenience.

XBMSD

NAME

xbmsd – Xbox Media Streaming Daemon

SYNOPSIS

xbmsd [options]

DESCRIPTION

xbmsd is a file sharing server that uses the Xbox Media Streaming Protocol (XBMSP) supported by the Xbox Media Center (XBMC). It also supports the XBMSP Server Discovery Protocol (XBSDP). This manual page is for xbmsd version 1.1.1.

The main features of xbmsd besides normal file sharing is mapping files to arbitrary local files or HTTP files/streams, the possibility of generating "synthetic" mplayer configuration files by file extension and the possibility of specifying file processing filters by file extension.

Mapping files to HTTP locations is useful because XBMC does not support HTTP locations natively.

Synthetic configuration files mean that files ending in a specified extension will all have a file-specific mplayer configuration file visible through xbmsd. One use for this is deinterlacing: if all files having the extension ".ts" are known to be either live or recorded DVB streams that need deinterlacing, then a configuration file containing the deinterlacing option (e.g. linear blend: "vf-pre=pp=lb") can be generated for all those files.

Filters can be specified for certain file extensions, and when a file with that extension is read it is fed to the filter program and the filter output is sent to the client as a stream instead of the file contents. Filters can be used to e.g. convert media files to another format on the fly. The downside is that since filter outputs are streams, they cannot be seeked.

OPTIONS

-c, --config_file configfile
Specify the configuration file to use. Otherwise use the default configuration file if it exists.
-d, --debug
Enables debugging output to the controlling tty and prevents the main program from forking into background. However, a connection handler process is still forked for each connection.
-D, --DEBUG
Same as --debug, but in addition the connection handler stays in the foreground. This means that only one connection at a time is possible and that the whole program dies if the connection handler dies (which it does if the client behaves badly).

In addition to these, all configuration file commands can also be given on the command line by prefixing the lower-case command with two dashes (e.g. --map foo /var/empty). Configuration options given on the command line override those in the configuration file.

CONFIGURATION FILE FORMAT

The configuration file consists of command and their arguments, one command per line. Empty lines and lines starting with a '#' are ignored. Commands and arguments are separated by whitespace. Quoting can be done with double or single quotes, the other kind of quote must be quoted with the other. Quoting is concatenative and non-escaped, meaning that "foo"'bar' and "foobar" are the same string. The commands are case-insensitive, the arguments are not unless so specified. The commands are described below.

root directory
Specify the server root directory. The directory must be an absolute path. The server won't start unless this is a valid directory.
map path realpath
Specify a file or directory mapping. The path is relative to the server root and must not begin or end with a "/". All the directories in the mapped path must either exist as real directories or mappings, they are not automatically mapped. The target realpath must be an absolute file or directory path beginning with a "/" or an HTTP URI beginning with "http://". HTTP mappings will be shown as streams to the client. If several mappings are specified for a path the first one is used.
conf type(s) file
Specify a "synthetic" mplayer configuration file to be generated for a given file extension. The type is specified as the file extension without the preceding dot and is case-insensitive. Multiple extensions can be specified with one command by separating the extensions with commas. The special case * matches any extension (but not files without an extension i.e. files without a dot in their name). If a file in a directory has the given extension then a synthetic configuration is generated by adding ".conf" to the file name. The synthetic file will map to the specified file, which is given either as a relative or an absolute path. Only if the file exists when checked from the current directory (the one where the "parent" file is) will a synthetic file be generated. However, the synthetic file is not generated if a file by that name either exists or is mapped to the directory. If several files are specified for a certain file type the first one that exists (relative to the current directory) is used.
filter type(s) program
Specify a filter program for files with the specified extension. The extensions are specified the same way as for the CONF command, and the path checking for the filter program is done relative to the current directory the same way as the file checking for the CONF command, but in addition the program needs to be executable. When a file matching the extension is opened and the specified program exists and is executable, the actual location of the file (this is the map target if the file was mapped, whether file name or HTTP URI) is given as the first argument to the filter and the filter program is executed. Everything the filter program writes to its standard output is sent to the XBMSP client as the contents of the file. Filtered files act like streams, so they are not seekable. This means that filters may not work if the option seek_streams is on, depending on the file/stream format produced by the filter.
pid pidfile
Specify the file where the main program PID is stored. This should be in a directory that is writable by the use xbmsd is run as. If xbmsd is started as root the PID file can be anywhere but it may not be possible for xbmsd to remove it upon termination, depending on the directory permissions. Also see Security Considerations below. There is no default value, so if left unspecified the PID will not be stored anywhere. In system-wide installations the PID file is usually specified in the system init script, in which case this should not be specified in the configuration file. In this case the possibly needed removal of the PID file after termination may also be handled by the init script.
listen address
Specify the address the server will listen on. Defaults to all local IPv4 addresses. If you want to listen on all IPv6 addresses you must specify "::" here (this will also listen on all IPv4 addresses on dual-stack (i.e. most) machines). The address is name-resolved, so it need not be numeric (e.g. "localhost" is valid). The listen address affects only the actual sharing server; server discovery still listens to all local addresses (IPv4 or IPv6, depending on the listen address type) unless the listen address is the loopback (localhost) address, in which case server discovery is disabled.
iface interface
Specify the network interface the server should use. The server will not receive packets from other interfaces. This option is only available on Linux systems.
port portnumber
Specify the TCP port which the daemon should listen. The default is 1400.
discovery_port portnumber
Specify the UDP port for the server discovery protocol. The default is 1400. If set to zero then server discovery is disabled.
hostname hostname
Specify the server comment string that is sent in server discovery packets. If not specified it defaults to the hostname of the host that xbmsd is running on, hence the name.
stat_interval kilobytes
If the size of a file grows after it has been opened by a XBMSP client, xbmsd won't allow reads beyond the original size unless the file is stat'ed again to obtain the changed size. As a system call stat(2) should not be called more often than necessary (although the overhead on modern operating systems is insignificant, but still...), so this sets the minimum amount of data in kilobytes that must be read by the client between stat calls. The default is 1024 i.e. one megabyte.
seek_streams boolean
If set to off, trying to seek a stream will return with an illegal seek error and do nothing, as streams are not seekable. If set to on, trying to seek a stream will still do nothing but return with success. Setting this to on may prevent bad mplayer behavior if seeking is (accidentally) tried when watching a stream. Note that setting this to on works only for media formats intended for streaming. For example, AVI files have an index at the end, so streaming AVI files (e.g. from the web or produced by a filter) with seeks that return success will cause the player (at least mplayer) to try and read the index and thus fail at playing the file. The default value is off.
stealth_filters boolean
Filtered files are streams and that is how their description is always given as a response to the XBMSP file info command. The file metadata is also returned for directory listings, and if this option is on then the directory listing will contain the metadata of the original file (so its size will show as that of the original file instead of zero). If this option is off, then the directory listings will also contain metadata that describes the filtered file as a stream. The default value is on.
user user
Specify the user name xbmsd should run as. If not specified it defaults to user nobody, so that xbmsd running as root (not a very good idea!) must be explicitly specified. This only has an effect if xbmsd is started as root.
group group
Specify the group that xbmsd should run as. If not specified it defaults to the default group of the user xbmsd is run as. This only has an effect if xbmsd is started as root.
password password
Specify a global password. If specified, every client must authenticate itself before it can do anything and ANY user can authenticate with this password. The password is given as plain text. Effectively disables the use of a password file.
password_file file
Specify a password file for authentication. An absolute path to the file must be given. If a password file is specified, every client must authenticate itself before it can do anything. The file has one entry per line in the format "user:type:encodedpassword". At present, the only supported type is "0", which means that the password is stored as plain-text in the third field. At present using a password file compared to the global password is not very useful, but future versions of xbmsd may implement access control based on the authenticated user, in which case the password file becomes more useful.

SECURITY CONSIDERATIONS

If started as root, xbmsd changes to run as an unprivileged user after PID file creation, defaulting to user nobody if no user was specified, but it is possible to leave xbmsd running as root if the user was explicitly specified as root. However, this is a VERY bad idea and you should only do it if you really, REALLY know what you are doing. You have been warned.

There is a race condition in creating the PID file if it is located on an NFS file system. This makes possible a linking attack that causes the target file to be overwritten by the PID file. This is especially dangerous if xbmsd is started as root. PID files should generally be located in "safe" directories i.e. ones that only the xbmsd user (and/or root) has write access to.

It should also be noted that the server discovery listening socket cannot be restricted to a specific IP network as it must receive all broadcasts, and it cannot be restricted to a specific network interface on non-Linux hosts. This means that you should disable server discovery if you are concerned that xbmsd might have security holes and your host has connections to both friendly and hostile networks.

FILES

/etc/xbmsd/xbmsd.conf
The default configuration file that is read unless one is specified with the '-c' option. The location of this file is determined at compile time and may be different between platforms.

REPORTING BUGS

Bug reports should be submitted to the SourceForge tracker linked on the program home page http://xbmsd.sourceforge.net/. Alternatively they can be sent via e-mail to to <jaatroko AT users DOT sourceforge DOT net>

AUTHOR

Juha Aatrokoski <jaatroko AT users DOT sourceforge DOT net>