dahdi_span_assignments.8: s/register/assign/
[dahdi/tools.git] / doc / dahdi_span_assignments.8
1 .TH "DAHDI_SPAN_ASSIGNMENTS" "8" "23 Jan 2014" "" ""
2
3 .SH NAME
4 dahdi_span_assignments \- handle DAHDI spans assignments
5 .SH SYNOPSIS
6
7 .B dahdi_span_assignments [\-v|\-\-verbose] [\-n|\-\-dry\-run] <add|remove|auto> \fB[\fIdevpath\fB...]
8
9 .B dahdi_span_assignments [\-v|\-\-verbose] list \fB[\fIdevpath\fB...]
10
11 .B dahdi_span_assignments [\-v|\-\-verbose] [\-k|\-\-key \fIkey\fB] dumpconfig
12
13 .B dahdi_span_assignments \-h|\-\-help
14
15 .SH DESCRIPTION
16 Channels in DAHDI devices (such as DAHDI PCI cards) are groups to logical
17 units called "spans" (for example: a port in a digital card is a span).
18 When the kernel module parameter \fBdahdi.auto_assign_span\fR is unset,
19 DAHDI devices that register with DAHDI don't cause their spans to be
20 automatically assigned.
21
22 This allows user-space to order DAHDI to assign them to specific span
23 and channel numbers. That way, specific spans on specific DAHDI devices
24 may be assigned with specific span and channel numbers \fBregardless\fR
25 of the registration order of the hardware (or if all hardware is present
26 at all).
27
28 .B dahdi_span_assignments
29 is used to assign those spans or to help creating the configuration
30 file used in their assignment:
31 .B /etc/dahdi/assigned-spans.conf .
32
33 .SH SUB-COMMANDS
34
35 There are several sub-commands.
36
37 All sub-commands take an optional list of paths to SysFS nodes of
38 devices. If given, the command will only operate on those DAHDI
39 devices. The default is to operate on all devices (which would normally
40 be the sane case when running from the command-line).
41
42 .B add \fB[\fIdevpath \fB...]
43 .RS
44 Applies to all devices or to those listed on the command line.
45 Parameters are paths (in SysFS) to DAHDI devices with unassigned
46 spans.
47
48 The command will assign spans with DAHDI according to
49 configuration in \fBassigned-spans.conf\fR.
50
51 If no line matches the span, or if the assignment for it fails (it is
52 not available) it will remain unassigned.
53
54 If any of the span settings fails (the span number or range of channels
55 is already in use), the program will print a message, but continue
56 applying the others. In such a case you should fix assigned-spans.conf
57 and re-run \fBadd\fR (or run \fBauto\fR to give those channels the
58 first available range and regenerate the file with 'dahdi_genconf
59 assignedspans').
60 .RE
61
62 .B remove \fB[\fIdevpath \fB...]
63 .RS
64 Applies to all devices or to those listed on the command line.
65 Parameters are paths (in SysFS) to DAHDI devices with assigned
66 spans.
67
68 The command will un-assign them.
69 .RE
70
71 .B auto \fB[\fIdevpath \fB...]
72 .RS
73 Applies to all devices or to those listed on the command line.
74 Parameters are paths (in SysFS) to DAHDI devices with unassigned
75 spans.
76
77 Each span is assigned to first available span number and channel
78 numbers, as if \fBdahdi.auto_assign_span\fR was set. The configuration
79 file doesn't affect these assignments.
80 .RE
81
82 .B list
83 .RS
84 List all spans in the system.
85 .RE
86
87 .B dumpconfig
88 .RS
89 List all assigned spans in the system in a format fit to be used in
90 \fBassigned\-spans.conf\fR. Use this to generate a configuration file after
91 you have (automatically or manually) assigned all existing spans.
92
93 .B dahdi_genconf assignedspans
94 uses this command internally.
95 .RE
96
97 .SH OPTIONS
98
99 .B \-v \-\-verbose
100 .RS
101 Verbose output.
102 .RE
103
104 .B \-n \-\-dry\-run
105 .RS
106 Don't assign / un-assign spans. Only print commands used to do so.
107 .RE
108
109 .B \-k \fIkey
110 .RS
111 For \fBdumpconfig\fR \- The key by which to identify the hardware in the
112 generated configuration. Legal values:
113
114 .B hwid
115 .RS
116 Hardware identifier (e.g.: software-readable serial number). This is the
117 default. If the device has no hwid, devpath is used.
118 .RE
119
120 .B location
121 .RS
122 The location field (file) in the SysFS device node (directory) for the
123 DAHDI device. If not available (typically: DAHDI version <= 2.7.x),
124 devpath is used.
125 .RE
126
127 .B devpath
128 .RS
129 Path in SysFS to the device node.
130 .RE
131 .RE
132
133 .SH CONFIGURATION
134 .B /etc/dahdi/assigned\-spans.conf
135 is a file with lines specifying assignment of spans.
136
137 Empty lines or lines beginning with '#' are ignored.
138
139 Each line is in the format of:
140
141 .I ID           spanspec ...
142
143 The \fIID\fR field specifies the DAHDI device and the \fIspanspecs\fR
144 define how to assign its spans. A line may have multiple
145 \fIspanspecs\fR in a single line (though dumpconfig generates a
146 configuration with one per line).
147
148 .SS Span Identifier
149 A DAHDI device may be specified either by a hardware identifier (a
150 software readable serial number or whatever) or the location in which
151 it is installed on the system. The former makes it simpler to change
152 connector / slot whereas the latter makes it simpler to replace a unit.
153
154 The value in this field is matched (when the commands \fBadd\fR and
155 \fBremove\fR) are used) to the following values:
156
157  \fIhwid\fR
158  \fB@\fIlocation\fR
159  \fIdevpath\fR
160
161 See above for their descriptions. The value may include shell wildcards:
162 *, ? and [], which are used in the match. The values to be matched are
163 first cleaned up: '!' is replaced with '/' and any character beyond
164 "a-zA-Z0-9/:.-" is removed.
165
166 .SS Span Specification
167
168 Each line should have one or more span specifications: this is the value
169 used to assign a span with DAHDI in the SysFS interface. A
170 specification has three colon-separated numbers:
171
172 .I rel_span_no:span_no:first_chan
173
174 for instance, the following are four span specifications for a quad-E1
175 device: 1:6:53 2:7:84 3:8:115 4:9:146 occupying spans 6-9 and channels
176 53-176.
177
178 .B rel_span_no
179 .RS
180 The relative number of the span in the device. E.g.: port number.
181 .RE
182
183 .B span_no
184 .RS
185 The desired DAHDI span number. Must be available.
186 .RE
187
188 .B first_chan
189 .RS
190 The desired DAHDI channel number for the first DAHDI channel in the span.
191 All channels of the span will be assigned following it and hence that
192 space must be available.
193 .RE
194
195
196 .SH ENVIRONMENT
197
198 .B DAHDICONFDIR
199 .RS
200 The directory in which assigned-spans.conf resides. /etc/dahdi if not
201 overridden from the environment.
202 .RE
203
204 .B DAHDISASSIGNEDSPANSCONF
205 .RS
206 The path to assigned-spans.conf resides. /etc/dahdi/assigned-spans.conf if
207 not overridden from the environment.
208 .RE
209
210 .B SPAN_ASSIGNMENTS_KEY
211 .RS
212 The default value for \-k . Defaults to "hwid" if not overridden from the
213 environment.
214 .RE
215
216
217 .SH FILES
218
219 .B /etc/dahdi/assigned-spans.conf
220 .RS
221 The default location for the configuration file.
222 .RE
223
224 .B /sys/bus/dahdi_devices/devices/\fIdevice\fR
225 .RS
226 SysFS node for the device. In this directory reside the following
227 files, among others:
228
229 .B location
230 .RS
231 The value of the device's location field.
232 .RE
233
234 .B assign_span, unassign_span, auto_assign
235 .RS
236 Write only files for the operations. Used by \fBadd\fR, \fBremove\fR and
237 \fBauto\fR, respectively.
238 .RE
239
240 .RE
241
242 .SH SEE ALSO
243 dahdi_span_types(8), dahdi_genconf(8), dahdi_cfg(8)
244
245 .SH AUTHOR
246 dahdi_span_assignments was written by Oron Peled.  This manual page was
247 written by Tzafrir Cohen. Permission is granted to copy, distribute
248 and/or modify this document under the terms of the GNU General Public
249 License, Version 2 any  later version published by the Free Software
250 Foundation.
251