dahdi_cfg: minor: Rename fo_real to dry_run
[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 and libraries. partial
53     targets of it:
54     * make 'utilname': builds 'utilname' alone (e.g: `make dahdi_diag`)
55     * make utils: Build just the programs.
56     * make libs: Build libtonezone.
57     * make tests: Build testing binaries.
58 . Install targets:
59   - make install: Install everything. Sub-targets of it:
60     * make install-utils: Installs most things.
61     * make install-libs: Installs libtonezone.
62   - make config: install configuration files (overriding existing ones).
63   - make install-test: Install testing binaries.
64
65
66 Installation to a Subtree
67 ^^^^^^^^^^^^^^^^^^^^^^^^^
68 The following may be useful when testing the package or when preparing a
69 package for a binary distribution (such as an rpm package) installing
70 onto a subtree rather than on the real system.
71
72   make install DESTDIR=targetdir
73
74 This can be useful for any partial install target from the list above.
75
76
77 Options For ./configure
78 ^^^^^^^^^^^^^^^^^^^^^^^
79 The configure script executes various tests and based on them generates
80 makeopts. You can pass it --with options and variable settings, for
81 instance:
82
83   ./configure --without-ncurses CC="gcc-4.10"
84
85 If you just want to recreate the same files without a full detection
86 run, use:
87
88   ./config.status
89
90 To re-run ./configure with the same parameters it was run with last
91 time, use:
92
93   ./config.status --recheck
94
95
96 Configuration
97 -------------
98 Configuration for DAHDI resides under /etc/dahdi . 
99
100 /etc/dahdi/system.conf
101 ~~~~~~~~~~~~~~~~~~~~~~
102 The main method to configure DAHDI devices is using the utility
103 *dahdi_cfg*. dahdi_cfg reads data from the configuration file 
104 /etc/dahdi/system.conf , figures out what configuration to send to 
105 channels, and send it to the kernel.
106
107 A sample annotated system.conf is included in this directory and
108 installed by default. Edit it to suit your configuration. Alternatively 
109 use the script dahdi_genconf to generate one that should work with your 
110 system. Note that while dahdi_genconf will generate a working configuration,
111 it will not automatically detect hardware echo cancellation modules.  These
112 will have to be enabled manually in system.conf.
113
114 /etc/dahdi/init.conf
115 ~~~~~~~~~~~~~~~~~~~~
116 The configuration file of the dahdi init.d script is
117 /etc/dahdi/init.conf . That file is used to override defaults that are 
118 set at the beginning of the init.d script.
119
120 Reference Configuration
121 ~~~~~~~~~~~~~~~~~~~~~~~
122 Sample system.conf
123 ^^^^^^^^^^^^^^^^^^
124 include::system.conf.asciidoc[]
125
126
127 Sample init.conf
128 ^^^^^^^^^^^^^^^^
129 include::init.conf.asciidoc[]
130
131
132 Sample genconf_parameters
133 ^^^^^^^^^^^^^^^^^^^^^^^^^
134 FIXME: still not properly formatted.
135
136 include::genconf_parameters.asciidoc[]
137
138
139 Sample assigned-spans.conf
140 ^^^^^^^^^^^^^^^^^^^^^^^^^^
141 include::assigned-spans.conf.asciidoc[]
142
143
144 Sample span-types.conf
145 ^^^^^^^^^^^^^^^^^^^^^^
146 include::span-types.conf.asciidoc[]
147
148
149 Tonezones
150 ~~~~~~~~~
151 The file zonedata.c contains the information about the tone zones used
152 in libtonezone (and hence also in dahdi_cfg). Here is a list of those zones:
153
154 include::tonezones.txt[]
155
156
157 DAHDI PERL modules
158 ~~~~~~~~~~~~~~~~~~
159 The directory xpp has, in addition to helper utilities for the
160 Xorcom Astribank, a collection of PERL modules to provide information
161 related to DAHDI. The PERL modules themselves are under xpp/perl_modules/ .
162 In xpp/ there are several utilities that use those modules:
163 - xpp-specific: dahdi_registration, xpp_sync, xpp_blink .
164 - General: lsdahdi, dahdi_genconf, dahdi_hardware, dahdi_drivers
165
166 The DAHDI PERL modules will currently only be automatically installed if you
167 happen to install the xpp directory. Those utilities require the PERL modules
168 to be installed, however they will also look for them in the directory 
169 perl_modules, and thus can be run directly from the DAHDI source tree. For 
170 example:
171
172   ./xpp/dahdi_hardware -v
173
174 To get usage information on a program, you can also use perldoc
175 (sometimes provided in a package separate from perl itself). For
176 instance:
177
178   perldoc ./xpp/lsdahdi
179
180 Some of them are specific for the Xorcom Astribank and described in its
181 documentation. the others are:
182
183 lsdahdi:: 
184   A somewhat glorified `cat /proc/dahdi/*`.
185 dahdi_genconf::
186   Generates configuration based on the existing DAHDI channels and on
187   /etc/dahdi/genconf_parameters (replaces genzaptelconf as well).
188 dahdi_drivers::
189   A two-liner script (not installed by default) that simply returns the
190   modules that should be modprobe-d on this system.
191 dahdi_hardware:: 
192   Uses the information from SysFS and its own knowledge to show
193   what PCI/USB DAHDI hardware is connected and if it is currently used
194   by a driver. Shows also some more information for Astribanks from
195   /proc/xpp .
196
197
198 PPP Support
199 ~~~~~~~~~~~
200 DAHDI digital cards can provide data channels through PPP as
201 point-to-point connections. This requires a plug-in to the PPP daemon
202 that is included in the ppp/ subdirectory. To install it:
203
204 1. Make sure you have the PPP source / headers installed. On Debian:
205
206    apt-get install ppp-dev
207
208 2. Run 'make' on the ppp subdirectory:
209
210    make -C ppp 
211    make -C ppp install
212
213 3. Make sure your kernel has support for both PPP (which is common is
214    distribution kernels and for HDLC (much less common) - CONFIG_PPP and
215    CONFIG_HDLC .
216
217
218 Initialization
219 --------------
220 This section documents the start up sequence of the DAHDI modules.
221
222 There are generally two options: explicit (using an init script) and
223 implicit (run from UDEV hook scripts).
224
225 Explicit
226 ~~~~~~~~
227 The dahdi init scripts does the following tasks:
228
229 * Loading the module dahdi and any other module listed in
230   /etc/dahdi/modules.
231 * For xpp (Astribanks) - some specific initializations. See
232   README.Astribank.
233 * Runs link:doc/dahdi_cfg.8.html[dahdi_cfg] after all modules were
234   loaded.
235 * A number of other tools may need to be run:
236 ** link:doc/fxotune.8.html[fxotune]
237 ** dahdihpec_enable
238
239 Only at this point Asterisk (or any other user of DAHDI) can be run.
240
241
242 Implicit
243 ~~~~~~~~
244 (Also known as "hot-plug" or "pinned-spans". This requires:
245
246 * dahdi >= 2.8.0
247 * Setting the module parameter auto_assign_spans of dahdi to 0
248 * (Recommended) Asterisk >= 12 - which supports "dahdi create channels".
249
250 When a device driver of a DAHDI device finishes initialization, it
251 creates a dahdi_device kernel object. A dahdi_device represents a single
252 DAHDI device (such as a PCI card) and may have several spans. If the
253 value of auto_assign_spans is 1 when dahdi_device is created, spans are
254 assigned automatically - each new span gets the first available span
255 number and range of channels. However if it is set to 0, spans will not
256 get assigned, and user space programs need to assign them. The
257 low-level interface for doing so is explained in the section "Span
258 Assignment" in the README of DAHDI-Linux.
259
260 New Devices
261 ^^^^^^^^^^^
262 When a kernel object is created or destroyed, the kernel sends an event
263 to user space. Those events are normally handled by udevd. Configurations
264 for udevd ("udev rules") may be placed in /etc/udev/rules.d or
265 /lib/udev/rules.d. This package installs rules that instruct udevd to
266 run the script `/usr/share/dahdi/dahdi_handle_device` on each new
267 device, which runs all the scripts in `/usr/share/dahdi/handle_device.d`.
268 Those scripts will:
269
270 * If `/etc/dahdi/span-types.conf` exists, apply it to the device. It is
271  used for E1/T1/J1 settings. See
272  <<_sample_span_types_conf,sample span-types.conf>>.
273
274 * If `/etc/dahdi/assigned-spans.conf` exists, assign the span according
275  to it (if it is not specified there: don't assign it).
276  used for E1/T1/J1 settings. See
277  <<_sample_assigned_spans_conf,sample assigned-spans.conf>>.
278
279 * But if that file does not exist, assign the span to the first
280   available place.
281
282 This script mainly uses the commands
283 link:doc/dahdi_span_types.8.html[dahdi_span_types] and
284 link:doc/dahdi_span_assignments.8.html[dahdi_span_assignments].
285
286 DAHDI devices are listed under `/sys/bus/dahdi_devices/devices`.
287
288 If you want to disable running this script, add the following line to
289 `/etc/dahdi/init.conf`:
290 .............................
291 DAHDI_UDEV_DISABLE_DEVICES=yes
292 .............................
293
294
295 New Spans
296 ^^^^^^^^^
297 Once a span is assigned, a kernel object will appear for it. It will be
298 listed under its device. As a new kernel object was created, an event is
299 sent to udev.
300
301 The standard DAHDI udev rules instruct udevd to run the script
302 `/usr/share/dahdi/dahdi_span_config` which runs all the scripts in
303 `/usr/share/dahdi/span_config.d`. Those script configures the new
304 span:
305
306 * If system.conf does not exist, generates a temporary configuration
307   for the span using link:doc/dahdi_genconf.8.html[dahdi_genconf
308   system].
309
310 * Runs link:doc/dahdi_cfg.8.html[dahdi_cfg] on the new span (using `-S`
311   and -C`).
312
313 * Runs `asterisk -rx 'dahdi create channels'` to add the new channels
314   and spans to Asterisk (if they were configured in advance).
315
316 If you want to disable running this script, add the following line to
317 `/etc/dahdi/init.conf`:
318 .............................
319 DAHDI_UDEV_DISABLE_SPANS=yes
320 .............................
321
322
323 New Channels
324 ^^^^^^^^^^^^
325 DAHDI channels have their own representation in the kernel. The standard
326 udev rules that dahdi-tools includes for them, however, don't run a
327 script for each device. Each DAHDI channel creates a block device file
328 at /dev/dahdi/chan/'span'/'rel-chan', where 'span' and 'rel-chan' are
329 each three-digit numbers (e.g: 035). 'span' is the span number and
330 'rel-chan' is the channel number relative to the span.
331
332 The udev rules generate the following extra symlinks under /dev/dahdi:
333
334 * /dev/dahdi/'num' - the channel number. As it was originally (but
335   continues beyond 250).
336 * /dev/dahdi/devices/'hardware_id'/'rel-span'/'rel-chan' - if the DAHDI
337   device has a hardware ID field, provide listing of the device's span
338   and channels.
339 * /dev/dahdi/devices/@'hardware_id'/'rel-span'/'rel-chan' - likewise for
340   the connector field. It has a "@" prefix.
341
342
343 include::UPGRADE.txt[]
344
345
346 License
347 -------
348 This package is distributed under the terms of the GNU General Public License
349 Version 2, except for some components which are distributed under the terms of
350 the GNU Lesser General Public License Version 2.1. Both licenses are included
351 in this directory, and each file is clearly marked as to which license applies.
352
353 If you wish to use the DAHDI drivers in an application for which the license
354 terms are not appropriate (e.g. a proprietary embedded system), licenses under
355 more flexible terms can be readily obtained through Digium, Inc. at reasonable
356 cost.
357
358
359 Reporting Bugs
360 --------------
361 Please report bug and patches to the Asterisk bug tracker at
362 http://bugs.digium.com/[] in the "DAHDI" category.
363
364
365 Links
366 -----
367 - http://asterisk.org/[] - The Asterisk PBX
368 - http://voip-info.org/[]
369 - http://voip-info.org/wiki/view/DAHDI[]
370 - http://docs.tzafrir.org.il/dahdi-tools/README.html[Up-to-date HTML version
371   of this file]