What the Remote Mode does - an Overview

As automated background recording is one of ZapDvb's key features, you will most likely setup a server with one or more DVB cards. The idea of remote mode is being able to access these resources from a desktop system or a computer configured for settop box mode. On the client side this saves extra DVB cards and the corresponding cabeling.

The remote mode is completely transparent to the user and zapmcc works as if the computer had a local DVB card. Even the client can do capturing and recording (although this is not advisable). The most obvious restriction is that all clients use the server on the same "life" priority level, in other words: at lowest priority. As a consequence each DVB activity on the server side has priority over the remote client (background recording and life activity). If a second remote client tries to access the same server side DVB card this client will receive a message saying that the server is busy. As a work-around it should be possible to configure multiple DVB cards for remote access, see below.

Configurating Client and Server

Step 1: The Client Setup

The client side only needs a little entry in zapdvb.conf section [zapdvb]:

# A client that only uses remote mode:
source0=myserver  net  0  1  " (Server)"  1650

# A client that mixes remote mode and a local DVB card:
source0=channels  sat  0  3  " (Local)"
source1=myserver  net  0  1  " (Server)"  1650

In the above example the parameters have the following functions:

Step 2: Migrating the Server to Family Mode

ZapDvb can be configured so that multiple users can share the same DVB hardware. As a consequence all users will also share the same atd and crontab entries for background recording. Technically this is implemented by using a shared user account named zapdvb (see the mainuser entry in zapdvb.conf). This account is also used in remote mode to run zapdvb as server. For more details see: Family Mode.

Remark: although the client could also be configured for family mode, this is not required.

Step 3: Configurating xinetd to run zapdvb as a Service

The super daemon xinetd is used to launch zapdvb dynamically as a server on client request. Please make sure that xinetd is installed. The daemon program uses the folder /etc/xinet.d to store configuration files. To make it work you will just have to add a little file named zapdvb to this folder (the setup program does this for you):

# We use tcp port 1650 to call the server! You may choose a different value,
# but make sure that the client's zapdvb.conf reflects your choice ...

service zapdvb
{       disable         = no
        type            = unlisted
        socket_type     = stream
        protocol        = tcp
        port            = 1650
        wait            = no
        user            = zapdvb
        group           = video
        env             = "PATH=/bin:/usr/bin:/usr/local/bin"
        server          = /usr/local/share/zapdvb/zapdvb
        server_args     = -S -q -c/usr/local/share/zapdvb/zapdvb.conf -p/usr/local/share/zapdvb/home/.zapdvb_run
}

Warning #1: Don't forget to restart xinetd after changing it's configuration. Try something like /etc/init.d/xinetd restart (the exact command depends on your Linux distribution).

Warning #2: If you are using very restrictive fire wall rules for your local network: make sure that the client can connect to the server via TCP/IP and that the server can open a data connection to client, see next section.

Multiple DVB cards and source statements

On client and server you can have up to four sourceN= statements (with N=0,1,2,3). These can be used to:

Remote mode cannot be recursive, e.g. on the server the sourceN= statement cannot forward to another server again.

It should be possible to configure multiple ports for zapdvb on the same server (if it has multiple DVB cards for example). This would allow clients to reach the same server via multiple sourceN= statements (each giving access to one DVB card). Each port would use a separate config file in /etc/xinet.d, and in such a case one would specify the sourceN= statement by adding the -a0 ... -a3 options to server_args.

How it works - the Protocol

Remote mode uses one or two TCP/IP connections. The 1st one is initiated by the client and causes xinetd to launch the server. This connection is used to send client requests to the server and to deliver error and information messages back to the client. Only text data is used here - you can even experiment with telnet to talk to the server if you want.

A 2nd connection will be opened by the server if it has to transfer data (from a DVB stream or a file) back to the client. For this connection the client allocates an ephemeral port number (e.g. an anonymous port having the port number assigned by the kernel). The client tells the server about this ephemeral port number so that the server can open the connection.

# The client request contains a verb and parameters. It looks like:
[call]
   # The 1st parameter is the verb. Supported verbs are:
   #   list - run 'zapdvb -l' on the server side
   #   kill - run 'zapdvb -k' on the server side
   #   play - tune to a channel and send the data to the client
   #   edit - launch 'zapdvb_cut --server'
   #   file - launch 'zapdvb_fil --server'
   #   load - download a file (not yet implemented)
   #   save - upload a file (not yet implemented)
   verb=play

   # Next is the ephemeral port number (0 for some verbs):
   port=32120

   # Finally two integer and two string argument are sent. The usage is:
   #   arg1 - channel number (from -n)
   #   arg2 - argument       (from -l or -k)
   #   str1 - channel name
   #   str2 - the -o filename  -or-  the -x parameter
   arg1=1
   arg2=0
   str1=
   str2=
[eof]

If the client uses the list, kill, edit or file verb, the server will respond with some lines of text (over the 1st connection) and quit. In other words: only one TCP/IP connection will by opened and the connection cannot be reused for more commands. Until the client receives a line starting with "[exit]" it should simply echo the returned data (to stderr for each line that starts with "zapdvb:" and to to stdout otherwise). The server sends the exit code for the command before it closes the connection.

# Simple status code sent by server:
[exit]
   code=3
[eof]

For the play, load and save verbs, the server will open the 2nd connection (for binary data) and send the following status info (through the text stream):

# The server might send status info like:
[zapdvb]
   # server process id, see family mode
   pid=3641
   # client must distinguish video and audio
   kind=video
   # the name of the tuned channel
   channel=Das Erste
   # the channel number
   number=1
   # the -a argument used by the server
   source=0
   command=-
   output=-
   level=0
   start=2005-06-19 10:33:24
   end=-
   capture=0
[eof]

The status information is mostly required by zapmcc to make the GUI work (e.g. displaying the currently tuned channel). After having received this information the client uses it to write the process information to a disk file and then eventually waits for (DVB-) data sent by the server. Finally the server will send it's exit code (through the text stream) as described above.

Future versions of the software may use a different protocol or may add more fields. So please do not rely too much on this document, which is intended for informational purposes only.