Commit 4289c550 authored by Cyril Deguet's avatar Cyril Deguet

- First version of the vls user's guide (at last!)

  (it is not completed yet)
parent 95b27ddf
......@@ -2,7 +2,7 @@
# vls (VideoLAN Server) main Makefile
#-------------------------------------------------------------------------------
# (c)1999-2001 VideoLAN
# $Id: Makefile,v 1.83 2001/12/12 15:37:02 bozo Exp $
# $Id: Makefile,v 1.84 2002/03/11 21:44:39 asmax Exp $
################################################################################
......@@ -162,7 +162,7 @@ dep: Makefile.opts $(DEP)
vls: Makefile.opts $(OBJ) $(BUILTINS)
@echo "Linking $@..."
@test -d bin || mkdir -p bin
$(CXX) $(LCFLAGS) -o bin/$@ $(OBJ) $(BUILTINS:%=obj/%.a) $(VLS_LIB)
$(CXX) $(LCFLAGS) -o bin/$@ $(OBJ) $(BUILTINS:%=obj/%.a) $(VLS_LIB) -pg
chmod 755 bin/$@
dep/server/vls.d: src/server/vls_builtins.cpp
......
<!DOCTYPE linuxdoc system>
<article>
<title>VideoLAN Server User's Guide</title>
<author>written by Cyril Deguet <htmlurl url="mailto:asmax@via.ecp.fr" name=
"&lt;asmax@via.ecp.fr&gt;">
<date>
$Id: vls-guide.sgml,v 1.1 2002/03/11 21:44:39 asmax Exp $
</date>
<abstract>
This document describes how to install, configure, and run the VideoLAN Server
(vls).
</abstract>
<toc>
<sect>Introduction
<sect1>What is the VideoLAN project ?
<p>
VideoLAN is a complete software solution for video streaming, developed by
students at the Ecole Centrale Paris, under the General Public License (GPL).
It has been designed for broadcasting MPEG2 videos on local area networks
(LAN), but it can be extended to metropolitan or wide area networks, thanks to
the multicast technology. The VideoLAN solution includes a server, which can
broadcast video streams from various sources (DVD, satellite, camera, ...),
a client, which can receive, decode and display MPEG2 streams and, if
necessary, a channel server which makes the client receive the right stream.
<verb>
DVD --->- Unicast/Broadcast/Multicast
\ ---
File --->-- -------- / \ --------
|->-| Server |=====>====| LAN |---->-----| Client |
Satellite ->-- | (VLS) | \ / | (VLC) |
/ -------- --- --------
MPEG2 -->- ^
encoder |
v
----------------
| Channel Server |
| (VLCS) |
----------------
</verb>
More details about the whole project can be found at
<htmlurl url="http://www.videolan.org">.
</sect1>
<sect1>What is the VideoLAN server (vls) ?
<p>
The VideoLAN Server (vls) was designed to read MPEG videos from various sources
(DVDs for instance) and broadcast them on a network, in MPEG2-TS format.
Depending on the network capabilities, the VideoLAN Server can send the streams
in unicast, broadcast, or multicast mode.
</sect1>
<sect1>Requirements
<sect2>Operating System
<p>
The VideoLAN Server is supposed to work under any Unix-like operating system.
A Windows port may be written one day or another ;)
</sect2>
<sect2>Software requirements
<p>
You will need <htmlurl url="http://www.dtek.chalmers.se/groups/dvd/downloads.shtml"
name="libdvdread"> if you want to stream DVDs with vls, and
<htmlurl url="http://www.videolan.org/libdvdcss/" name="libdvdcss"> for reading
encrypted DVDs.
</sect2>
<sect2>Hardware requirements
<p>
Vls is a very light software and needs few ressources. A Pentium 100 MHz
with 32 MB of memory should be enough for broadcasting one stream (then it
takes about 50% of CPU time). On my Pentium III 800 MHz, I can broadcast
more than 5 streams and vls eats less than 1% of CPU ! When broadcasting a
lot of streams stored on a hard disk, the actual limitation is not the
processor but the disk (especially when using IDE disks).
</sect2>
</sect1>
<sect1>Contact us
<p>
If you have any questions about the VideoLAN Server, you can contact us
at our mailing-list <htmlurl url="mailto:vls@videolan.org"
name="vls@videolan.org">
</sect1>
</sect>
<sect>Installation
<sect1>Getting vls
<p>
You can get tarballs and binary packages for the VideoLAN Server at the vls
<htmlurl url="http://www.videolan.org/vls/download.html" name="download"> page.
Currently, there are binary packages only for Debian GNU/Linux, so if you
use another operating system, you will have to download the source code
(tarball) and build vls by hand (but don't worry, it is very easy ;-)
To install the Debian package, you can type something like:
<tscreen><verb>
# dpkg -i vls_0.3.1-1_i386.deb
</verb></tscreen>
If you have downloaded the source tarball, uncompress it with:
<tscreen><verb>
# tar xvzf vls-0.3.1.tar.gz
</verb></tscreen>
You can also get the source code through CVS, with the following commands:
<tscreen><verb>
# export CVSROOT=:pserver:anonymous@cvs.videolan.org:/cvs/videolan
# cvs login
[there is no password, just press enter]
# cvs checkout vls
# cvs logout
</verb></tscreen>
</sect1>
<sect1>Compiling vls
<p>
The VideoLAN Server uses the GNU configure and build system. It means that
you will need the standard GNU utilities, such as make, gcc, ld, and so
on...
<sect2>Configuration
<p>
The first step is to create the <tt/Makefile/ thanks to the <tt/configure/
script. For a basic configuration, juste run:
<tscreen><verb>
# ./configure
</verb></tscreen>
You can supply several options to <tt/configure/, to change the installation
directories, for instance. Run <tt>./configure --help</tt> to get a list of
all options available. Here is an explanation of vls-specific options:
<tscreen>
<verb>--with-words=(big|little)</verb>
<tscreen>Specify endianness when cross-compiling. Don't use this option if
you don't know what it means !
</tscreen>
</tscreen>
<tscreen>
<verb>--disable-debug</verb>
<tscreen>Disable debug mode (enabled by default).
</tscreen>
</tscreen>
<tscreen>
<verb>--enable-profiling</verb>
<tscreen>Generate extra code to write profile information suitable for the
analysis program gprof.
</tscreen>
</tscreen>
<tscreen>
<verb>--disable-dvd</verb>
<tscreen>Disable DVD support (enabled by default). You must supply this
option if you don't have libdvdread installed.
</tscreen>
</tscreen>
</sect2>
<sect2>Building
<p>
To compile and link vls, just type:
<tscreen><verb>
# make
</verb></tscreen>
Afterwards, there should be a binary called <tt/vls/ in the <tt/bin/
subdirectory. There sould be also a library called <tt/dvdreader.so/, if you
enabled DVD support.
</sect2>
</sect1>
<sect1>Installing vls
<p>
To install vls files, run
<tscreen><verb>
# make install
</verb></tscreen>
If you haven't changed the install directories with <tt/configure/ options
(<tt/--prefix=DIR/ for instance), these directories are:
<itemize>
<item><tt>/usr/local/bin</tt> for binary files (<tt/vls/)
<item><tt>/usr/local/lib/videolan/vls</tt> for plugins (<tt/dvdreader.so/)
<item><tt>/usr/local/etc/videolan/vls</tt> for configuration file
(<tt/vls.cfg/)
</itemize>
</sect1>
<sect>Overview and basic concepts
<sect1>Vls structure
<p>
From a user's point of view, the VideoLAN Server can be divided into four
kinds of components: a <tt/manager/, <tt/inputs/, <tt/converters/, and
<tt/channels/.
<verb>
File, --------- ------------- ----------- Network,
DVD, --> | INPUT |---->| CONVERTER |---->| CHANNEL |--> File,
... --------- ------------- ----------- ...
\ ----------- /
----------| MANAGER |----------
-----------
^
|
Administration Interface
</verb>
<sect2>Input
<p>
The role of an <tt/input/ is to read MPEG streams from a given source
(file, DVD, device, ...), and feed the right <tt/converters/ with these
streams. An input may be able to read several streams, which are called
<tt/programs/. There are currently two kinds of inputs: the <tt/local input/,
which can read videos from files or DVDs, and the <tt/video input/, which has
been designed for reading streams from Video4Linux devices (/dev/video) able
to produce MPEG streams. Both inputs are able to read MPEG1 or MPEG2 streams,
either in PS or TS format. Of course, you can use several inputs and play
several programs at the same time.
</sect2>
<sect2>Converter
<p>
The role of a <tt/converter/ is to receive a stream from an input,
and convert it into the MPEG-TS format. If you don't know what PS or TS
are, here is some explanation. When you play a MPEG video from a DVD, for
instance, the MPEG stream is actually composed of several streams (called
Elementary Streams): there is one stream for video, one for audio, another
for subtitles, and so on. These different streams are mixed together into
a single Program Stream (PS). So, the .VOB files you can find in a DVD are
actually MPEG2-PS files. But this PS format is not adapted for broadcasting
video through a network or by satellite, for instance. So, another format
called Transport Stream (TS) was designed for broadcasting MPEG videos
through such channels. The VideoLAN Server is able to convert PS streams
(from DVDs, for instance) into TS streams (ps2ts converter). Of course, it
can also read TS streams, and fix them by handling stream discontinuities
(ts2ts converter).
</sect2>
<sect2>Channel
<p>
A <tt/channel/ receives a stream from a converter, and send it to a given
destination (network, file, ...). If you want, you can call a "channel" an
"output": it is the same thing ;-). Currently, two kinds of channels are
supported: <tt/network/ and <tt/file/. Note that, at the moment, the VideoLAN
Server can support only one output per stream, so you cannot play a stream on
the network and write it into a file at the same time. The network output
is highly configurable: you can choose which network interface you want to
use, and specify source and destination IP addresses. Of course, all that
becomes very interesting when your destination is a broadcast or multicast
address !
</sect2>
<sect2>Manager
<p>
The <tt/manager/ controls the way streams are broadcasted. Through an
<tt/administration interface/, you can tell the manager to start, stop,
suspend or resume the different programs. You can also get a list of all
programs available in the Program Table. The manager gets this table from
the vls configuration file (<tt/vls.cfg/), so it cannot be changed once vls
has been started. At the moment, you cannot ask the manager whether a given
stream is being broadcasted, but you will get an error message if you try
to stop a stream that was not broadcasted.
</sect2>
</sect1>
<sect1>Administration interface
<p>
Once vls has been started, you must use an <tt/administration interface/
to communicate with the manager. Currently, there is only a telnet interface
to communicate with vls. A command line interface and a GTK interface are
to be written. When using the telnet interface, you must authenticate
before typing any command, because any user may not be allowed to execute
any command (it can be configured in <tt/vls.cfg/).
</sect1>
</sect>
<sect>Configuration
<p>
The VideoLAN Server reads its configuration from <tt/vls.cfg/, which is
supposed to be located in the current directory or in
<tt>SYSCONF_DIR/videolan/vls</tt> (where SYSCONF_DIR is <tt>/usr/local/etc</tt>
if you built and installed vls by hand, or is <tt>/etc</tt> if you installed
the debian binary package).
To write a <tt/vls.cfg/, just copy/paste the example <tt/vls.cfg/ supplied
with vls ;-)
If it is not enough for you, here are the full details:
<sect1>General structure
<p>
The VideoLAN Server configuration file <tt/vls.cfg/ is divided into sections,
and each section may contain several variables:
<tscreen><verb>
BEGIN "FirstSection"
Variable1 = "value1"
Variable2 = "value2"
[...]
END
BEGIN "SecondSection"
Variable1 = "value1"
Variable3 = "value3"
[...]
END
[...]
</verb></tscreen>
All section names, variable names and values are not case-sensitive.
There can be empty sections and subsections. Comments must follow a #
character. Some variables have a default value; it means that you can ommit
to declare these variables, and then they will be given their default value.
</sect1>
<sect1>Writing a <tt/vls.cfg/
<p>
Here is an explanation of all the sections you can find in a <tt/vls.cfg/:
<sect2>Section "Vls"
<p>
This section contains application wide settings.
<tscreen>
<verb>LogFile = "name"</verb>
<tscreen>
Name of vls log file. Default is "vls.log"
</tscreen>
</tscreen>
Example:
<tscreen><verb>
BEGIN "Vls"
LogFile = "vls.log"
END
</verb></tscreen>
</sect2>
<sect2>Section "Groups"
<p>
In this section, you can define some groups of users, and which commands
these users are allowed to execute. For each group you want to define,
you must add a line in the following format:
<tscreen>
<verb>groupname = "command1|command2|..."</verb>
<tscreen>
This adds a group "groupname", the users of which are allowed to execute
command1, command2, and so on. At the moment, the available commands are:
help, browse, start, suspend, resume, stop, shutdown, logout.
</tscreen>
</tscreen>
Example:
<tscreen><verb>
BEGIN "Groups"
monitor = "help|browse|logout"
master = "help|browse|start|resume|suspend|stop|shutdown|logout"
END
</verb></tscreen>
</sect2>
<sect2>Section "Users"
<p>
This section contains a list of users allowed to control vls through an
administration interface. For each user, add a line in the following format:
<tscreen>
<verb>username = "password:groupname"</verb>
<tscreen>
This adds a user "username", who belongs to the group "groupname" (defined
in the "Groups" section) and can log in with the password "password".
BE CAREFUL: the password must be encrypted, with a tool such as
<tt/mkpasswd/, or with the UNIX function "crypt".
</tscreen>
</tscreen>
Example:
<tscreen><verb>
BEGIN "Users"
monitor = "3BcKWoiQn0vi6:monitor" # password is 'monitor'
admin = "42BKiCguFAL/c:master" # password is 'Vir4Gv5S'
END
</verb></tscreen>
</sect2>
<sect2>Section "Telnet"
<p>
In this section, you can configure the telnet administration interface.
<tscreen>
<verb>LocalPort = "port"</verb>
<tscreen>
Defines which port will be used for the telnet server. Default port is
"9999".
</tscreen>
</tscreen>
<tscreen>
<verb>Domain = "domain"</verb>
<tscreen>
Either "inet4" or "inet6" (default is "inet4"). If you want to use IPv4
addresses, put "inet4", and if you want to use IPv6, put "inet6".
</tscreen>
</tscreen>
<tscreen>
<verb>LocalAddress = "IP address"</verb>
<tscreen>
Defines on which IP address the telnet server will listen for requests.
Default address is "0.0.0.0" (or "0::0" with IPv6)
</tscreen>
</tscreen>
Example:
<tscreen><verb>
BEGIN "Telnet"
LocalPort = "9999"
END
</verb></tscreen>
</sect2>
<sect2>Section "NativeAdmin"
<p>
Same syntax as "Telnet". Not used yet.
</sect2>
<sect2>Section "Inputs"
<p>
In this section, you can define which inputs you want to use. For each input
you need, add a line in the following format:
<tscreen>
<verb>InputName = "Type"</verb>
<tscreen>
This adds a input named "InputName", the type of which is "Type". As
explained before, there are currently two types of input: "local" and
"video". You must use the "local" input to play a stream from a file or a
DVD, and the "video" input to play a stream from a Video4Linux device.
Each input must be configured in its own section (see next paragraph).
</tscreen>
</tscreen>
Example:
<tscreen><verb>
BEGIN "Inputs"
local1 = "local"
kfir = "video"
END
</verb></tscreen>
</sect2>
<sect2>Inputs configuration
<p>
For each input declared in the "Inputs" section, you must add a section with
the same name as the corresponding input. For instance, if you declared
two inputs "local1" and "kfir", there should be two sections named "local1"
and "kfir" too. The syntax of such sections depends on the type of the
corresponding input.
To configure a local input, add a section in the following format:
<tscreen>
<verb>
BEGIN "LocalInputName"
ConfigPath = "path"
END
</verb>
<tscreen>
"LocalInputName" is the name of the local input you want to configure.
Actually this section only tells the VideoLAN Server where to find the
configuration file for this input, called <tt/input.cfg/ (its syntax will
be explained later). If the "ConfigPath" variable is set, vls will look
for this file in the directory "path", otherwise it will look for it in
the root directory ('/').
</tscreen>
</tscreen>
To configure a video input, add a section in the following format:
<tscreen>
<verb>
BEGIN "VideoInputName"
Device = "device"
Type = "type"
END
</verb>
<tscreen>
"VideoInputName" is the name of the video input you want to configure.
"device" is the path of the Video4Linux you want to read from (default
is "/dev/video"). "type" is either "Mpeg2-PS" or "Mpeg2-TS", depending
on your device configuration (default is "Mpeg2-PS").
</tscreen>
</tscreen>
Example:
<tscreen><verb>
BEGIN "local1"
ConfigPath = "/home/videolan/streams"
# the configuration file is /home/videolan/streams/input.cfg
END
BEGIN "kfir"
Device = "/dev/video"
Type = "Mpeg2-PS"
END
</verb></tscreen>
</sect2>
<sect2>Section "Channels"
<p>
In this section, you can define the channels (outputs) you want to use.
For each channel you need, add a line in the following format:
<tscreen>
<verb>ChannelName = "Type"</verb>
<tscreen>
This adds a channel named "ChannelName", the type of which is "Type".
"Type" must be either "network" or "file". Like inputs, channels must be
configured in their own section.
</tscreen>
</tscreen>
Example:
<tscreen><verb>
BEGIN "Channels"
localhost = "network"
client1 = "network"
client2 = "network"
multicast = "network"
localfile = "file"
END
</verb></tscreen>
</sect2>
<sect2>Channels configuration
<p>
For each channel declared in the "Channels" section, you must add a section
with the same name as the corresponding channel. The syntax of such a section
depends on the type of the corresponding channel.
To configure a network channel, add a section in the following format:
<tscreen>
<verb>
BEGIN "NetChannelName"
SrcHost = "SourceHost"
SrcPort = "SourcePort"
DstHost = "DestHost"
DstPort = "DestPort"
Type = "Type"
TTL = "ttl"
Domain = "Domain"
Interface = "Interface"
END
</verb>
<tscreen>
"NetChannelName" is the name of the network channel you want to configure.
"SourceHost" is the IP address (or DNS name) from which vls will send
the stream. "SourcePort" is the UDP port from which the stream will be sent.
"SrcHost" and "SrcPort" are optional (if you don't set them, vls will not
'bind' the socket).
"DestHost" is the IP address (or DNS name) to which the stream will be sent.
"DestPort" is the UDP port to which the stream will be sent (default is
"1234"). "Type" is either "unicast", "broadcast" or "multicast" (default is
"unicast"), depending on what you want to do (and on your "DstHost" address).
"TTL" is an option useful only if "Type" is "multicast" (default value is
"0"). You can use it to increase the TTL of your multicast packets if they
have to cross several routers.
"Domain" is either "inet4" if you use IPv4 addresses, or "inet6" if you use
IPv6 (default is "inet4").
"Interface" is an option only supported under linux, to force the stream to
be broadcasted through a given network interface, "eth1" for instance" (to
use this option, vls must have root permissions).
</tscreen>
</tscreen>
To configure a file channel, add a section in the following format:
<tscreen>
<verb>
BEGIN "FileChannelName"
FileName = "file"
Append = "append"
END
</verb>
<tscreen>
"FileChannelName" is the name of the file channel you want to configure.
"file" is the name of the file where the stream will be stored (default
is "fileout.ts"). "append" is either "yes" or "no", and indicates whether
vls will append the stream at the end of the file, or rewrite it.
</tscreen>
</tscreen>
Example:
<tscreen><verb>
BEGIN "localhost" # The client is on the same host as the server
DstHost = "localhost"
DstPort = "1234"
END
BEGIN "client1" # unicast towards client1
DstHost = "192.168.1.2"
DstPort = "1234"
END
BEGIN "client2" # unicast towards client2
DstHost = "192.168.1.3"
DstPort = "1234"
END
BEGIN "multicast" # multicast streaming
DstHost = "239.2.12.42"
DstPort = "1234"
Type = "multicast"
END
BEGIN "localfile" # file output
FileName = "stream.ts"
Append = "no"
END
</verb></tscreen>
</sect2>
</sect1>
<sect1>Writing an <tt/input.cfg/
<p>
As explained before, a local input must be configured in a separate file,
named <tt/input.cfg/, which is divided into sections, like <tt/vls.cfg/.
In this file you can define several <tt/programs/, each program being a MPEG
stream (a file, for instance).
An <tt/input.cfg/ must contain an "Input" section, with the following syntax:
<tscreen>
<verb>
BEGIN "Input"
FilesPath = "path"
ProgramCount = "count"
END
</verb>
<tscreen>
"path" is the path where your MPEG files are located (by default it is the
current directory). "count" is the number of programs defined in input.cfg
(0 by default).
</tscreen>
</tscreen>
For each program you want to define, you must add a section with the following
format:
<tscreen>
<verb>
BEGIN "number"
Name = "name"
Type = "type"
FileName = "file"
Device = "device"
END
</verb>
<tscreen>
"number" is the program number: the first program has number 1, the second
number 2, and so on. "name" is the program name, by which you will tell vls
to start this program (see next chapter "Running vls"). "type" can be
"Mpeg1-PS", "Mpeg1-TS", "Mpeg2-PS", "Mpeg2-TS", or "Dvd". If your stream
is stored in a MPEG file (*.mpeg, *.mpg, *.vob, and so on...), it is
probably in Mpeg1-PS or Mpeg2-PS format. If Type is set to "Mpeg1-PS",
"Mpeg1-TS", "Mpeg2-PS", or "Mpeg2-TS", vls will assume your stream is
stored in the file "file", in the directory "path" ("path" being the
variable defined in the "Input" section). If "type" is "Dvd", the variable
Device will be used instead of FileName. Note that you cannot play "Dvd"
programs unless you compiled vls with dvd support, which uses libdvdread.
With libdvdread, you can play a "real" Dvd (then "device" is the device
of your DVD drive, "/dev/hdc" or "/dev/cdrom", for instance; note that
libdvdread needs read AND write access rights to the device), but you can
also play a Dvd stored on a hard disk (then "device" is the directory
where the .vob files are stored: "/mnt/data/VIDEO_TS", for instance).
The libdvdread now supports encrypted Dvds, even stored on a hard disk.
</tscreen>
</tscreen>
Full example:
<tscreen><verb>
BEGIN "Input"
FilesPath = "/home/videolan/streams"
ProgramCount = "4"
END
BEGIN "1" # MPEG2 stream stored in /home/videolan/streams/Dolby.vob
Name = "dolby"
FileName = "Dolby.vob"
Type = "Mpeg2-PS"
END
BEGIN "2" # another file
Name = "canyon"
FileName = "Dolby_Canyon.vob"
Type = "Mpeg2-PS"
END
BEGIN "3" # Dvd
Name = "dvd"
Device = "/dev/cdrom"
Type = "Dvd"
END
BEGIN "4" # Dvd stored on a hard disk
Name = "matrix"
Device = "/mnt/data/matrix/VIDEO_TS"
Type = "Dvd"
END
</verb></tscreen>
</sect1>
</sect>
<sect>Running vls
<sect1>Launching vls
<p>
Running vls is very easy: just type "vls" in a shell console, and that's all.
Be careful: if your log file is "vls.log" as in the example, vls will need
write access in the current directory , or you will see something like:
<tscreen><verb>
*** Exception *** in copy constructor (0xbffffc98, copy of 0x80e30a8)
Unable to open the log file "vls.log": Error: Could not open file 'vls.log':
Permission denied
</verb></tscreen>
Remember also that you must be root when using the "Interface" option in
<tt/vls.cfg/.
If everything is right, you will see something like:
<tscreen><verb>
VideoLAN Server v 0.3.0 (Dec 22 2001) - (c)1999-2001 VideoLAN
2002-03-09 17:24:51 [INFO/Vls] Module "channel:file" registered
2002-03-09 17:24:51 [INFO/Vls] Module "channel:network" registered
2002-03-09 17:24:51 [INFO/Vls] Module "mpegreader:file" registered
2002-03-09 17:24:51 [INFO/Vls] Module "mpegconverter:ts2ts" registered
[...]
</verb></tscreen>
What you can see on the screen (stderr) is exactly what goes in the log
file <tt/vls.log/.
When vls has been successfully started, it doesn't take any command from
its standard input, so you can put it into background (you can use the
"screen" utility to do that).
</sect1>
<sect1>Using the telnet interface
<p>
After vls has been launched, it opens a telnet server (on the port 9999 by
default). You can connect to this server with the following command:
<tscreen><verb>telnet localhost 9999</verb></tscreen>
You should see something like:
<tscreen><verb>
Trying 127.0.0.1...
Connected to vls.
Escape character is '^]'.
Videolan Server Administration System
Login:
</verb></tscreen>
Then you must authenticate with a login/password pair defined in <tt/vls.cfg/.
When you have been successfully authenticated, you should see a prompt like:
<tscreen><verb>