path: root/README

                       runvdr extreme


Written by:            Udo Richter <udo_richter(a)gmx.de>
Project's homepage:    http://projects.vdr-developer.org/projects/runvdr-extreme
See the file COPYING for license information.



About
--------------------------------------------------------------------------
runvdr extreme is a runvdr script, just like the runvdr script included in
the VDR distribution. Its just roughly 17 times bigger.

Some of the features of runvdr extreme:

- Loads default configuration from runvdr.conf
- All configuration accessible and overrideable from command line
- All VDR options handled
- Handles runvdr.pid file, acts on signals
- Can launch an X server for output plugins
- Restarts VDR in case of errors
- Commands to restart VDR and reload DVB
- Configuration file re-read on VDR restart
- Avoids endless loops if VDR crashes instantly
- Resets terminal to defaults after VDR terminated
- Add wrapper commands to VDR for debugging
- Waiting for the VDR process to be killed completey,
  hard killing after timeout
- Command line help
- Can switch console terminal
- Can set locale for VDR daemon
- Optionally supports pluginsetup-plugin
- Optionally supports setup-plugin

Additional features of runvdr-conf.d:

- Loads configuration files in alphabetical order from a
  directory, comparable to init.d directories.
- Command line tool to activate/deactivate plugins
- Control the load order of plugins
- Optional: Menu configuration using osdserver plugin



Quick-start
--------------------------------------------------------------------------
- Copy runvdr to /usr/local/bin/ or whereever you like
- Copy runvdr.conf.example to /etc/runvdr.conf if you want to run VDR as
  server, or ~/.runvdr.conf if you want to run it as user.
- Edit the runvdr.conf to match your needs

The runvdr.conf is pretty much self-explaining. All runvdr.conf options are
also available on command line, see --help.

For the init-script (Debian):
- Copy init.d.runvdr.Debian to /etc/init.d/runvdr
- Use sysv-rc-conf or update-rc.d to set up startup runlevel

For runvdr-conf.d:
- Copy runvdr-conf.d to /usr/local/bin/
- Create /etc/runvdr/ and fill it with files like skeleton.example
- Add INCLUDE /etc/runvdr/conf.d/* to runvdr.conf
- Use runvdr-conf.d show|enable|disable to configure the plugins
- (Optional) Add "runvdr-conf.d osdserver" to commands.conf.



Details
--------------------------------------------------------------------------

Options take this precedence:

1. Command line options have highest precedence
2. runvdr.conf file specified by -C or --runvdr-conf
3. If no -C and no --runvdr-conf specified, use ~/.runvdr.conf
4. If no -C and no --runvdr-conf and no ~/.runvdr.conf, use /etc/runvdr.conf
5. If none of the above, runvdr built-in defaults are used.

Only one of the runvdr.conf files is loaded by default, and only one -C
option is evaluated. However, you can load the contents of another runvdr.conf
file from a runvdr.conf by using the INCLUDE directive. For example, you can
load /etc/runvdr.conf from within ~/.runvdr.conf to just override some of
the settings for the current user.

The INCLUDE directive also supports multiple files per line. By that, you can
use INCLUDE /etc/runvdr/conf.d/* to load a whole directory full of config
files at once. For example, you can put files (or symlinks) for each plugin
to load into that directory, containing a single line "AddPlugin xxx".

Plugins added by the AddPlugin directive in the conf file and the --plugin
and -P command line option can be removed again from the list of plugins
by specifying "AddPlugin -name", --plugin="-name" or -P-name.
The name part acts as a pattern to the beginning of the plugin name, all
plugins matching "name*" will be dropped. Especially "AddPlugin -" and -P- will
drop all plugins from the list. The same mechanism works for the -D device
parameter.

To pass parameters to VDR without parsing by runvdr, use -- as paramenter.
All parameters after -- will be directly passed to VDR. For erxample,
"runvdr -- --help" will show the command line help of VDR instead of runvdr.



runvdr-conf.d
--------------------------------------------------------------------------

The runvdr-conf.d is an (optional) tool to manage plugins. It works simillar
to the init.d concept, where a whole directory of symbolic links is loaded
in alphabetical order.

In case of runvdr-conf.d, one file similar to the skeleton.example file
is placed in /etc/runvdr/ for each plugin that is available. Only plugins
that have a symbolic link in /etc/runvdr/conf.d/ to their config file will
be loaded. For this, the corresponding INCLUDE line must be enabled in
runvdr.conf.

The following commands are available to manage the plugins:

runvdr-conf.d show [name]
  Shows all plugins (resp. only the 'name' plugin), including the full name
  and the load priority. 'name' is the file name in the /etc/runvdr/
  directory.

runvdr-conf.d enable name [--prio XX]
  Activates a plugin for next restart. Uses default priority or the specified
  priority. For that, a symbolic link to /etc/runvdr/name will be created
  under /etc/runvdr/conf.d/XXname.

runvdr-conf.d disable name
  Deactivates a plugin from next restart on, by deleting the symbolic link
  under /etc/runvdr/conf.d/XXname.

runvdr-conf.d osdserver [--debug]
  Connects to the osdserver plugin and allows interactive plugin configuration
  using the VDR OSD. From there, plugins can be activated and deactivated,
  and the load priority can be changed.
  Without --debug, runvdr-conf.d returns immediately, disconnection standard
  input/output, so it can be started from commands.conf. With --debug, the
  osdserver communication will be shown.



Dependencies
--------------------------------------------------------------------------
Unix commands, that runvdr uses:

Command       Debian packet
 pgrep         procps
 ps            procps
 sleep         coreutils
 date          coreutils
 chvt          console-tools
 getopt        util-linux



Examples
--------------------------------------------------------------------------
Assuming you've set up your defaults in /etc/runvdr.conf, here are some
cool things you can do now:


Start VDR in background (for example with TERMINAL=/dev/tty8 in conf file):

  runvdr &

Stop VDR and the runvdr script:

  runvdr --terminate

Dito, but wait until VDR is killed:

  runvdr --terminate --wait

Restart the already running VDR process because it is hanging, or because
the runvdr.conf has changed:

  runvdr --restart

Dito, but also reload the DVB drivers:

  runvdr --dvb-restart

Use the new fresh compiled VDR for the first time:

  runvdr --vdr=/usr/src/vdr-1.5.0/vdr --lib=/usr/src/vdr-1.5.0/PLUGINS/lib

For debugging, start VDR with no terminal redirection:

  runvdr --terminal="" --switchterminal=""

Load all plugins and also the hello plugin:

  runvdr -P hello

Load only the hello plugin:

  runvdr -P- -P hello

Load all plugins, but not the hello-plugin:

  runvdr -P-hello

Do a dry-run of runvdr:

  runvdr --wrapper=echo

Do a debugging session:

  runvdr --wrapper="gdb --args"

Start with a completely different setup:

  runvdr --runvdr-conf="/etc/runvdr-debugging.conf"