document the usage of live_dahdi

git-svn-id: http://svn.asterisk.org/svn/dahdi/linux/trunk@7180 a0bf4364-ded3-4de4-8d8a-66a801d63aff

1 files changed, 148 insertions, 0 deletions

diff --git a/README b/README
index ad6a421..0171445 100644
--- a/README
+++ b/README
@@ -179,6 +179,154 @@ be reported on the
 https://lists.sourceforge.net/lists/listinfo/freetel-oslec[OSLEC mailing
 list].
 
+Live Install
+~~~~~~~~~~~~
+In many cases you already have DAHDI installed on your system but would
+like to try a different version. E.g. in order to check if the latest
+version fixes a bug that your current system happens to have.
+
+DAHDI-linux includes a script to automate the task of installing DAHDI
+to a subtree and using it instead of the system copy. Module loading
+through modprobe cannot be used. Thus the script pre-loads the required
+modules with insmod (which requires some quesswork as for which modules
+to load). It also sets PATH and other environment variables to make all
+the commands do the right thing.
+
+There is an extra mode of operation to copy all the required files to a
+remote host and run things there, for those who don't like to test code
+on thir build system.
+
+Live Install: The Basics
+^^^^^^^^^^^^^^^^^^^^^^^^
+Basic operation is through running
+
+  ./build_tools/live_dahdi
+
+from the root directory of the dahdi-linux tree. Using DAHDI requires
+dahdi-tools as well, and the script builds and installs dahdi-tools. By
+default it assumes the tree of dahdi-tools is in the directory
+'dahdi-tools' alongside the dahdi-linux tree.  If you want to checkout
+the trunks from SVN, use:
+
+  svn checkout http://svn.asterisk.org/svn/dahdi/linux/trunk dahdi-linux
+  svn checkout http://svn.asterisk.org/svn/dahdi/tools/trunk dahdi-tools
+  cd dahdi-linux
+
+If the tools directory resides elsewhere, you'll need to edit
+live/live.conf (see later on). The usage message of live_dahdi:
+
+ Usage:                    equivalent of:
+ live_dahdi configure      ./configure
+ live_dahdi install        make install
+ live_dahdi config         make config
+ live_dahdi unload         /etc/init.d/dahdi stop
+ live_dahdi load           /etc/init.d/dahdi start
+ live_dahdi reload         /etc/init.d/dahdi restart
+ live_dahdi xpp-firm       (Reset and load xpp firmware)
+ live_dahdi rsync TARGET   (copy filea to /tmp/live in host TARGET)
+ live_dahdi exec  COMMAND  (Run COMMAND in 'live' environment)
+
+Normally you should run:
+
+ ./build_tools/live_dahdi configure
+ ./build_tools/live_dahdi install
+ ./build_tools/live_dahdi config
+
+to build and install everything. Up until now no real change was done.
+This could actually be run by a non-root user. All files are installed
+under the subdirectory live/ .
+
+Reloading the modules (and restarting Asterisk) is done by:
+
+ ./build_tools/live_dahdi reload
+
+Note: this stops Asterisk, unloads the DAHDI modules, loads the DAHDI
+modules from the live/ subdirectory, configures the system and re-starts
+Asterisk. This *can* do damage to your system. Furthermore, the DAHDI
+configuration is generated by dahdi_genconf. It can be influenced by
+a genconf_parameters file. But it may or may not be what you want.
+
+If you want to run a command in the environment of the live system, use
+the command 'exec':
+
+ ./build_tools/live_dahdi lsdahdi
+ ./build_tools/live_dahdi dahdi_hardware -v
+
+Note however:
+
+ ./build_tools/live_dahdi dahdi_cfg -c live/etc/dahdi/system.conf
+
+Live Install Remote
+^^^^^^^^^^^^^^^^^^^
+As mentioned above, live_dahdi can also copy all the live system files
+to a remote system and run from there. This requires rsync installed on
+both system and assumes you can connect to the remove system through
+ssh.
+
+  tzafrir@hilbert $ ./build_tools/live_dahdi rsync root@david
+  root@david's password:
+  <f+++++++++ live_dahdi
+  cd+++++++++ live/
+  <f+++++++++ live/live.conf
+  cd+++++++++ live/dev/
+  cd+++++++++ live/dev/dahdi/
+  cd+++++++++ live/etc/
+  cd+++++++++ live/etc/asterisk/
+  cd+++++++++ live/etc/dahdi/
+  <f+++++++++ live/etc/dahdi/genconf_parameters
+  <f+++++++++ live/etc/dahdi/init.conf 
+  ...
+
+As you can see, it copies the script itselfand the whole live/
+subdirectory. The target directory is /tmp/live on the target directory
+(changing it should probably be simple, but I never needed that).
+
+Then, on the remove computer:
+
+  root@david:/tmp# ./live_dahdi reload
+
+
+Configuring a Live Install
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+The live_dahdi script reads a configuration file in 'live/live.conf' if
+it exists. This file has the format of a shell script snippet:
+
+ var1=value # a '#' sign begins a comment
+ var2='value'
+
+ # comments and empty lines are ignored
+ var3="value"
+
+The variables below can also be overriden from the environment:
+
+ var1='value' ./build_tools/live_dahdi
+
+===== LINUX_DIR
+The relative path to the dahdi-linux tree. The default is '.' and normally
+there's no reason to override it.
+
+===== TOOLS_DIR
+The relative path to the dahdi-tools tree. The default is 'dahdi-tools'.
+
+===== XPP_SYNC
+Set a syncing astribank. See xpp_sync(8). Default is 'auto'.
+
+===== AST_SCRIPT
+The command for an init.d script to start/stop Asterisk. Should accept 
+'start' and 'stop' commands. Use 'true' if you want to make that a
+no-op. Defaults to '/etc/init.d/asterisk' .
+
+===== MODULES_LOAD
+Manual list of modules. They will be loaded by insmod. If reside in a 
+subdir, add it explicitly. Modules for the drivers that are detected on
+the system will be added by the script. Default: 'dahdi
+dahdi_echocan_mg2'
+
+===== REMOVE_MODULES
+A list of modules to remove when unloading. Will be resolved
+recursively. The default is 'dahdi'. You may also want to have 'oslec'
+or 'hpec' there if you use them.
+
 
 Module Parameters
 -----------------