README: indentation level for config samples
[dahdi/tools.git] / README
1 DAHDI Telephony Interface Driver
2 =================================
3 Asterisk Development Team <asteriskteam@digium.com>
4 $Revision$, $Date$
5
6 DAHDI stands for Digium Asterisk Hardware Device Interface. This
7 package contains the user-space tools to configure the kernel modules
8 included in the package dahdi-linux.
9
10 Build Requirements
11 ------------------
12 This package needs the headers from dahdi-linux. Thus you should install
13 dahdi-linux before building dahdi-tools.
14
15 Build System
16 ~~~~~~~~~~~~
17 GCC and friends. Generally you will need to install the package gcc.
18 There may be cases where you will need a specific version of gcc to build
19 kernel modules.
20
21
22 Extra Libraries
23 ~~~~~~~~~~~~~~~
24 Some libraries are needed for extra utilities that are provided with
25 DAHDI.
26
27 - libusb is needed for building fpga_load, needed for firmware loading of
28   the Xorcom Astribank.
29 - libnewt is needed to build the optional but useful utility dahdi_tool.
30
31
32 Installation
33 ~~~~~~~~~~~~
34 Note: If using `sudo` to build/install, you may need to add /sbin to your PATH.
35 ----------------------------------
36 ./configure
37 make
38 make install
39 # To install init scripts and config files:
40 #make config
41 ----------------------------------
42
43
44 Build Tweaks
45 ~~~~~~~~~~~~
46 Partial Build/Install
47 ^^^^^^^^^^^^^^^^^^^^^
48 There are some make targets that are provided to build or install just
49 parts of DAHDI:
50
51 . Build targets:
52   - make: Build DAHDI user-space programs. partial
53     targets of it:
54     * make 'utilname': builds 'utilname' alone (e.g: `make dahdi_diag`)
55     * make utils: Build libtonezone.
56     * make libs: Build libtonezone.
57 . Install targets:
58   - make install: Installs user space tools into /usr/sbin/ (TODO - list
59     partial targets)
60   - make config: should be run once to configure 
61
62
63 Installation to a Subtree
64 ^^^^^^^^^^^^^^^^^^^^^^^^^
65 The following may be useful when testing the package or when preparing a
66 package for a binary distribution (such as an rpm package) installing
67 onto a subtree rather than on the real system.
68
69   make install DESTDIR=targetdir
70
71 This can be useful for any partial install target from the list above.
72
73
74 Options For ./configure
75 ^^^^^^^^^^^^^^^^^^^^^^^
76 The configure script executes various tests and based on them generates
77 makeopts. You can pass it --with options and variable settings, for
78 instance:
79
80   ./configure --without-ncurses CC="gcc-4.10"
81
82 If you just want to recreate the same files without a full detection
83 run, use:
84
85   ./config.status
86
87 To re-run ./configure with the same parameters it was run with last
88 time, use:
89
90   ./config.status --recheck
91
92
93 Configuration
94 -------------
95 Configuration for DAHDI resides under /etc/dahdi . 
96
97 /etc/dahdi/system.conf
98 ~~~~~~~~~~~~~~~~~~~~~~
99 The main method to configure DAHDI devices is using the utility
100 *dahdi_cfg*. dahdi_cfg reads data from the configuration file 
101 /etc/dahdi/system.conf , figures out what configuration to send to 
102 channels, and send it to the kernel.
103
104 A sample annotated system.conf is included in this directory and
105 installed by default. Edit it to suit your configuration. Alternatively 
106 use the script dahdi_genconf to generate one that should work with your 
107 system. Note that while dahdi_genconf will generate a working configuration,
108 it will not automatically detect hardware echo cancellation modules.  These
109 will have to be enabled manually in system.conf.
110
111 /etc/dahdi/init.conf
112 ~~~~~~~~~~~~~~~~~~~~
113 The configuration file of the dahdi init.d script is
114 /etc/dahdi/init.conf . That file is used to override defaults that are 
115 set at the beginning of the init.d script.
116
117 Reference Configuration
118 ~~~~~~~~~~~~~~~~~~~~~~~
119 Sample system.conf
120 ^^^^^^^^^^^^^^^^^^
121 include::system.conf.asciidoc[]
122
123
124 Sample init.conf
125 ^^^^^^^^^^^^^^^^
126 include::init.conf.asciidoc[]
127
128
129 Sample genconf_parameters
130 ^^^^^^^^^^^^^^^^^^^^^^^^^
131 FIXME: still not properly formatted.
132
133 include::genconf_parameters.asciidoc[]
134
135
136 Sample assigned-spans.conf
137 ^^^^^^^^^^^^^^^^^^^^^^^^^^
138 include::assigned-spans.conf.asciidoc[]
139
140
141 Sample span-types.conf
142 ^^^^^^^^^^^^^^^^^^^^^^
143 include::span-types.conf.asciidoc[]
144
145
146 Tonezones
147 ~~~~~~~~~
148 The file zonedata.c contains the information about the tone zones used
149 in libtonezone (and hence also in dahdi_cfg). Here is a list of those zones:
150
151 include::tonezones.txt[]
152
153
154 DAHDI PERL modules
155 ~~~~~~~~~~~~~~~~~~
156 The directory xpp has, in addition to helper utilities for the
157 Xorcom Astribank, a collection of PERL modules to provide information
158 related to DAHDI. The PERL modules themselves are under xpp/perl_modules/ .
159 In xpp/ there are several utilities that use those modules:
160 - xpp-specific: dahdi_registration, xpp_sync, xpp_blink .
161 - General: lsdahdi, dahdi_genconf, dahdi_hardware, dahdi_drivers
162
163 The DAHDI PERL modules will currently only be automatically installed if you
164 happen to install the xpp directory. Those utilities require the PERL modules
165 to be installed, however they will also look for them in the directory 
166 perl_modules, and thus can be run directly from the DAHDI source tree. For 
167 example:
168
169   ./xpp/dahdi_hardware -v
170
171 To get usage information on a program, you can also use perldoc
172 (sometimes provided in a package separate from perl itself). For
173 instance:
174
175   perldoc ./xpp/lsdahdi
176
177 Some of them are specific for the Xorcom Astribank and described in its
178 documentation. the others are:
179
180 lsdahdi:: 
181   A somewhat glorified `cat /proc/dahdi/*`.
182 dahdi_genconf::
183   Generates configuration based on the existing DAHDI channels and on
184   /etc/dahdi/genconf_parameters (replaces genzaptelconf as well).
185 dahdi_drivers::
186   A two-liner script (not installed by default) that simply returns the
187   modules that should be modprobe-d on this system.
188 dahdi_hardware:: 
189   Uses the information from SysFS and its own knowledge to show
190   what PCI/USB DAHDI hardware is connected and if it is currently used
191   by a driver. Shows also some more information for Astribanks from
192   /proc/xpp .
193
194
195 PPP Support
196 ~~~~~~~~~~~
197 DAHDI digital cards can provide data channels through PPP as
198 point-to-point connections. This requires a plug-in to the PPP daemon
199 that is included in the ppp/ subdirectory. To install it:
200
201 1. Make sure you have the PPP source / headers installed. On Debian:
202
203    apt-get install ppp-dev
204
205 2. Run 'make' on the ppp subdirectory:
206
207    make -C ppp 
208    make -C ppp install
209
210 3. Make sure your kernel has support for both PPP (which is common is
211    distribution kernels and for HDLC (much less common) - CONFIG_PPP and
212    CONFIG_HDLC .
213
214
215 include::UPGRADE.txt[]
216
217
218 License
219 -------
220 This package is distributed under the terms of the GNU General Public License
221 Version 2, except for some components which are distributed under the terms of
222 the GNU Lesser General Public License Version 2.1. Both licenses are included
223 in this directory, and each file is clearly marked as to which license applies.
224
225 If you wish to use the DAHDI drivers in an application for which the license
226 terms are not appropriate (e.g. a proprietary embedded system), licenses under
227 more flexible terms can be readily obtained through Digium, Inc. at reasonable
228 cost.
229
230
231 Reporting Bugs
232 --------------
233 Please report bug and patches to the Asterisk bug tracker at
234 http://bugs.digium.com/[] in the "DAHDI" category.
235
236
237 Links
238 -----
239 - http://asterisk.org/[] - The Asterisk PBX
240 - http://voip-info.org/[]
241 - http://voip-info.org/wiki/view/DAHDI[]
242 - http://docs.tzafrir.org.il/dahdi-tools/README.html[Up-to-date HTML version
243   of this file]