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.

The default name of the config file is generated from the executable filename
suffixed by ".conf". So you may have easy access to different config files,
without having to use the -C parameter every time, by creating symlinks to
runvdr.

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"