dahdi_span_types: allow defaults + overrides
[dahdi/tools.git] / doc / dahdi_span_types.8
1 .TH "DAHDI_SPAN_TYPES" "8" "23 Jan 2014" "" ""
2
3 .SH NAME
4 dahdi_span_types \- set line modes of DAHDI spans before assignment
5 .SH SYNOPSIS
6
7 .B dahdi_span_types [\fIoptions\fB] <list|dumpconfig|set> \fB[\fIdevpath \fB...]
8
9 .SH DESCRIPTION
10 The span type (the line mode: E1/T1/J1) must be set to a span before
11 DAHDI assigns it a span number, as E1 spans use more channels.
12 \fBdahdi_span_types\fR applies the span type configuration to an
13 un-assigned span.
14
15 Using it only makes sense when the kernel module parameter
16 \fBdahdi.auto_assign_span\fR is unset, otherwise DAHDI automatically
17 assign span numbers during device registration.
18
19 .B dahdi_span_types
20 takes a command and an optional list of devices. If no device is given,
21 the command is applied to all devices.
22
23 The device is marked as a path in the SysFS tree.
24
25 .SH OPTIONS
26
27 .B -h|--help
28 .RS
29 Output usage message and exit
30 .RE
31
32 .B -n|--dry-run
33 .RS
34 During \fB"set"\fR operation, only show what would be done, without actually
35 changing anything.
36 .RE
37
38 .B -v|--verbose
39 .RS
40 During \fB"set"\fR operation, show the actions that are being performed.
41 .RE
42
43 .SH SUB-COMMANDS
44 .B set
45 .RS
46 Reads settings from \fBspan-types.conf\fR and applies them to the
47 device(s) specified in the command line (or all devices, if none
48 specified).
49 .RE
50
51 .B list
52 .RS
53 List line modes for all spans in the system which may be set with
54 dahdi_span_types (E1/T1/J1 spans).
55 .RE
56
57 .B dumpconfig
58 .RS
59 List types for the spans in a format fit to be used in
60 \fBspan-types.conf\fR. Use this to generate a configuration file after
61 you have (perhaps manually) set all existing spans.
62
63 .B dahdi_genconf spantypes
64 uses this command internally.
65 .RE
66
67 .SH CONFIGURATION
68 .SS General structure
69 .B span-types.conf
70 is a file with lines specifying line modes of spans.
71
72 Empty lines or lines beginning with '#' are ignored.
73
74 Each line is in the format of:
75
76 .I ID           spanspec ...
77
78 The \fIID\fR field specifies the DAHDI device and the \fIspanspecs\fR
79 define the line modes of its spans. A line may have multiple
80 \fIspanspecs\fR in a single line (though dumpconfig generates a
81 configuration with one per line).
82
83 .SS Span Identifier
84 A DAHDI device may be specified either by a hardware identifier (a
85 software readable serial number or whatever) or the location in which
86 it is installed on the system. The former makes it simpler to change
87 connector / slot whereas the latter makes it simpler to replace a unit.
88
89 The value in this field is matched (when the command \fBset\fR is
90 used) to the following values:
91
92  \fIhwid\fR
93  \fB@\fIlocation\fR
94  \fIdevpath\fR
95
96 See above for their descriptions. The value may include shell wildcards:
97 *, ? and [], which are used in the match. The values to be matched are
98 first cleaned up: '!' is replaced with '/' and any character not in
99 "a-zA-Z0-9/:.-" is replaced by "_".
100
101 Note that while span\-types.conf allows an arbitrarily-complex
102 combination of E1, J1 and T1 ports, it would normally have just a single
103 wildcard line setting the line mode (the first line in the example below).
104
105 .SS Span Specification
106
107 Each line should have one or more span specifications: this is the value
108 used to set span type with DAHDI in the SysFS interface. A
109 specification has two colon-separated fields:
110
111 .I rel_span_no:span_type
112
113 for instance, the following are four span specifications specify ports 1
114 and 2 as E1 and ports 3 and 4 as T1: [12]:E1 [34]:T1 .
115
116 .B rel_span_no
117 .RS
118 The relative number of the span in the device. E.g.: port number.
119 This field may contain shell wildcards (*, ? and [])
120 .RE
121
122 .B span_type
123 .RS
124 E1/T1/J1
125 .RE
126
127 .SS Multiple matches
128 During \fBset\fR operation, the \fBdahdi_span_types\fR applies all
129 matching settings to a span. This is done in the order of lines in the
130 configuration files.
131
132 Thus, if there are multiple matches to a span -- the last match
133 will \fIwin\fR (all will be applied to the kernel in order. The last
134 one in the file will be applied last).
135
136 Example:
137 .EX
138 *             *:T1      # All spans on all devices will be T1
139 usb:X1234567  [34]:E1   # Except spans 3,4 on the device which will be E1
140 .EE
141
142
143 .SH ENVIRONMENT
144
145 .B DAHDICONFDIR
146 .RS
147 The directory in which span-types.conf resides. /etc/dahdi if not
148 overridden from the environment.
149 .RE
150
151 .B DAHDISPANTYPESCONF
152 .RS
153 The path to span-types.conf resides. /etc/dahdi/span\-types.conf if
154 not overridden from the environment.
155 .RE
156
157
158 .SH FILES
159
160 .B /etc/dahdi/span\-types.conf
161 .RS
162 The default location for the configuration file.
163 .RE
164
165 .B /sys/bus/dahdi_devices/devices/\fIdevice\fR
166 .RS
167 SysFS node for the device. In this directory reside the following
168 files, among others:
169
170 .B spantype
171 .RS
172 read/write file. Reading from it returns current configuration for spans
173 of the device. Span-specifications can be written to it to change line
174 modes (but only for a span that is not assigned yet).
175 .RE
176
177
178 .SH SEE ALSO
179 dahdi_span_assignments(8), dahdi_genconf(8), dahdi_cfg(8)
180
181 .SH AUTHOR
182 dahdi_span_types was written by Oron Peled.  This manual page was
183 written by Tzafrir Cohen. Permission is granted to copy, distribute
184 and/or modify this document under the terms of the GNU General Public
185 License, Version 2 any  later version published by the Free Software
186 Foundation.
187