File: znetconf.8

package info (click to toggle)
s390-tools 2.3.0-1
  • links: PTS
  • area: main
  • in suites: bullseye, buster, sid
  • size: 6,176 kB
  • sloc: ansic: 87,755; sh: 8,398; cpp: 8,384; perl: 3,783; makefile: 1,476; asm: 654
file content (475 lines) | stat: -rw-r--r-- 10,435 bytes parent folder | download
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
.\" Copyright 2017 IBM Corp.
.\" s390-tools is free software; you can redistribute it and/or modify
.\" it under the terms of the MIT license. See LICENSE for details.
.\"
.TH ZNETCONF 8 "Mar 2009" "s390-tools"

.SH NAME
znetconf \- list and configure network devices for System z network adapters

.SH SYNOPSIS
.B znetconf
.B [-h|--help] [-v|--version]
.br

.br
.B znetconf -u | -c
.br
.B znetconf -a <device_bus_id>[,...]{2} [-o <ATTR>=<VALUE>]+ [-d <DRIVER>]
.br
.B znetconf -A [-o <ATTR>=<VALUE>]+ [-d <DRIVER>] [-e <device_bus_id>]+
.br
.B znetconf -r <device_bus_id> [-n] | -R [-n] [-e <device_bus_id>]+


.SH DESCRIPTION
The znetconf command lists and automatically configures network devices for
System z network adapters. It senses and lists potential
network devices that are not yet configured or already configured.
Based on these lists, it automatically adds or removes network devices.
.P
For automatic configuration, znetconf builds a channel command word
(CCW) group device from sensed CCW devices, configures any specified
option through the sensed network device driver and sets the new
network device online.
.P
During automatic removal, znetconf sets the device offline and removes it.
Be aware that removing all network devices leads to the
complete loss of network connectivity. So a terminal session (e.g. 3270)
might be required to restore.

.SH OPTIONS
.TP 8
.BR -h | --help
Print help text.

.TP 8
.BR -v | --version
Print the version of the s390-tools package and the znetconf command.

.TP
.BR -u | --unconfigured
List potential network devices that are not yet configured.
For each device, the following data is provided:
.RS
.TP 4
*
Device IDs (device bus-IDs) of the CCW devices constituting the network
device
.TP
*
Type of control unit (e.g. 1731/01)
.TP
*
Network card type (e.g. OSA (QDIO))
.TP
*
Channel path identifier (CHPID)
.TP
*
Device driver (qeth, lcs, ctc, ctcm)
.RE
.TP
.BR -c | --configured
List configured network devices. For each device, the following data is
provided:
.RS
.TP 4
*
Device IDs (device bus-IDs) of the CCW devices constituting the network device
.TP
*
Control unit type (e.g. 1731/01)
.TP
*
Card type (e.g. GuestLAN QDIO)
.TP
*
Channel path identifier (CHPID)
.TP
*
Driver (qeth, lcs, ctc, ctcm)
.TP
*
Network interface name (if available)
.TP
*
State (online vs. offline)
.RE

.TP
.BR -a | --add " <device_bus_id>[,<device_bus_id>)][,<device_bus_id>]
[-o | --option <ATTR>=<VALUE>]+ [-d | --driver <DRIVER>]
.br

.br
Add the potential network device identified by device_bus_id.
device_bus_id can be any of the device
IDs listed as part of the potential network device list (argument
.BR -u ")."
For example, if znetconf
.BR -u
lists 0.0.f503,0.0.f504,0.0.f505 for a potential network device, device_bus_id
may be 0.0.f503 or 0.0.f504 or 0.0.f505.
If a device bus-ID begins with 0.0., you can abbreviate it to the final
hexadecimal digits. For example, you can abbreviate 0.0.f503 to f503.
.br
.br
If attribute value pairs are given with
.BR -o ", "
these pairs are configured for the created network device. The
device is then set online regardless of whether the given attribute value pairs
were applied successfully.
.br
Finally, the corresponding network interface name (e.g. eth1) is displayed.
.br
If more then one device_bus_id is given, the given set of devices is configured as a network device. znetconf tries to sense the required device driver
automatically. If the device driver cannot be sensed, you must specify it with
-d.
.BR -d "."
With
.BR -d
znetconf does NOT check the validity of the combination of device bus-IDs.

.TP
.BR -A | --addall " [-o | --option <ATTR>=<VALUE>]+ [-d | --driver DRIVER]"
[-e | --except <device_bus_id>]+
.br

.br
Add all potential network devices. If one or more device_bus_id are specified
with
.BR -e ", "
the corresponding network devices are not added.
Attribute value pairs given with
.BR -o
are configured for the network devices before they are set
online. If the configuration of one potential network device fails,
znetconf continues with the next remaining potential network device.

.TP
.BR -r | --remove " <device_bus_id> [-n | --non-interactive]"
Remove the network device identified by device_bus_id. device_bus_id is one of
the device IDs of the network device. They are listed as part of znetconf
.BR -c "."
znetconf sets the device offline and removes it. If
.BR -n
is given, all confirmation questions are answered with 'yes'.

.TP
.BR -R|--removall " [-n | --non-interactive] [-e | --except <device_bus_id>]+"
Remove all network devices. If
.BR -n
is given, all confirmation questions are answered with 'yes'. To exclude
certain devices from the removal, their device bus-IDs have to be given
with
.BR -e ". "

.TP
\fB<ATTR>\fR
Specify a device option. The option must match a sysfs attribute for the device
to be configured. For a detailed description of the semantics of sysfs 
attributes please refer to the Device Drivers, Features, and Commands book for 
Linux on System z. The attributes are:

.RS
.B qeth
.br
broadcast_mode
.br
buffer_count
.br
canonical_macaddr
.br
checksumming
.br
fake_broadcast
.br
ipa_takeover/add4
.br
ipa_takeover/add6
.br
ipa_takeover/del4
.br
ipa_takeover/del6
.br
ipa_takeover/enable
.br
ipa_takeover/invert4
.br
ipa_takeover/invert6
.br
isolation
.br
large_send
.br
layer2
.br
performance_stats
.br
portname
.br
portno
.br
priority_queueing
.br
route4
.br
route6
.br
rxip/add4
.br
rxip/add6
.br
rxip/del4
.br
rxip/del6
.br
vipa/add4
.br
vipa/add6
.br
vipa/del4
.br
vipa/del
.br
sniffer
.RE

.RS
.B ctc(m)
.br
buffer
.br
loglevel
.br
protocol
.br
stats
.RE

.RS
.B lcs
.br
portno
.br
lancmd_timeout
.RE

.RS
.B NOTE:
for
.BR qeth ", some attributes are specific to layer 2 or layer 3 mode
of operation. The option "layer2=[0|1]" must be specified before
such attributes in the command line, thus it is recommended to always
specify it first.
.RE

.TP
\fB<device_bus_id>\fR
Specify the device bus-ID of a CCW device. Device bus-IDs have the form
([A-Fa-f0-9].[A-Fa-f0-9].)[A-Fa-f0-9]{4}.

If a device bus-ID begins with 0.0., you can abbreviate it to the final
hexadecimal digits.

For example, you can abbreviate 0.0.f503 to f503.

.TP
\fB<DRIVER>\fR
Specify the device driver for the device. Valid values are qeth, lcs, ctc, or
ctcm.

.SH EXAMPLES
\fBznetconf -A\fR
.RS
Configures all potential network devices. To display a list of all potential
network devices enter znetconf
.BR -u "."
After running znetconf
.BR -A
enter znetconf
.BR -c
to see which devices have been configured successfully.
You can also enter znetconf
.BR -u
to display devices that have not been configured successfully.
Successfully configured devices are no longer listed with znetconf
.BR -u "."
.RE
.P
\fBznetconf -A -e f500\fR
.RS
Configures all potential network devices except the one with the device bus-ID
0.0.f500. To display a list of all potential network devices enter znetconf
.BR -u "."
After running \fBznetconf -A -e f500\fR
enter znetconf
.BR -c
to see which devices have been configured successfully.
You can also enter znetconf
.BR -u
to display devices that have not been configured successfully.
Successfully configured devices are no longer listed with znetconf
.BR -u "."
.RE
.P
\fBznetconf -R\fR
.RS
Removes all configured network devices.
After successfully running this command, all devices listed by znetconf -c
become potential devices listed by
.BR -u "."
.RE
.P
\fBznetconf -R -e f501\fR
.RS
Removes all configured network devices except the one having the device bus-ID
0.0.f501.
After successfully running this command, all devices listed by znetconf -c
except the one having the device bus-ID 0.0.f501 become potential devices
listed by
.BR -u "."
.RE
.P
\fBznetconf -u\fR
.RS
Shows the list of potential network devices. Example output:
.br

.br
Device IDs                 Type    Card Type  CHPID Drv.
.br
--------------------------------------------------------
.br
0.0.f500,0.0.f501,0.0.f502 1731/01 OSA (QDIO) 00    qeth
.br
0.0.f503,0.0.f504,0.0.f505 1731/01 OSA (QDIO) 01    qeth
.RE
.P
\fBznetconf -a 0.0.f503\fR
.RS
Adds the potential network device
with 0.0.f503 as one of its device bus-IDs.
After successfully running this command, znetconf
.BR -c
lists the new network device.
.RE
.P
\fBznetconf -a f503\fR
.RS
This command is equivalent to \fBznetconf -a 0.0.f503\fR.
.RE
.P
\fBznetconf -a f503 -o layer2=0 -o portname=myname\fR
.RS
Adds the potential network device
with 0.0.f503 as one of its device bus-IDs
and configures the options layer2 with value 0 and
portname with myname.
.RE
.P
\fBznetconf -c\fR
.RS
Shows a list of configured network devices. Example output:
.br

.br
Device IDs                 Type    Card Type     CHPID Drv. Name State
.br
-----------------------------------------------------------------------
.br
0.0.f503,0.0.f504,0.0.f505 1731/01 GuestLAN QDIO    01 qeth eth1 online
.br
0.0.f5f0,0.0.f5f1,0.0.f5f2 1731/01 OSD_1000         76 qeth eth0 online
.RE
.P
\fBznetconf -r 0.0.f503\fR
.RS
Removes the network device with 0.0.f503 as one of its device bus-IDs.
You can only remove configured devices as listed by znetconf
.BR -c "."
After successfully running this command the corresponding device appears in the
list of potential network devices as listed by znetconf
.BR -u "."
.RE
.P
\fBznetconf -r f503\fR
.RS
This command is equivalent to \fBznetconf -r 0.0.f503\fR.
.RE
.P

.SH DIAGNOSTICS
If znetconf runs successfully, the exit status is 0. In case of errors, the following codes are returned:
.TP
.BR 0
success
.TP
.BR 9
could not group devices
.TP
.BR 10
could not set device online
.TP
.BR 11
could not set device offline
.TP
.BR 12
invalid attribute value pair
.TP
.BR 13 
missing component (broken installation)
.TP
.BR 15
invalid device ID format
.TP
.BR 17
unknown driver
.TP
.BR 19
invalid argument
.TP
.BR 20
too much arguments
.TP
.BR 21 
no configuration found for device ID
.TP
.BR 22
device is not configured
.TP
.BR 23
could not ungroup device
.TP
.BR 24
at least one option could not be configured
.TP
.BR 25
missing value for attribute
.TP
.BR 26
device does not exist
.TP
.BR 27
device already in use
.TP
.BR 28
net device did not come online
.TP
.BR 29
some devices could not be added or failed
.TP
.BR 30
syntax error on command line
.TP
.BR 31
ccwgroup devices do not exist
.TP
.BR 99
internal znetconf bug
.SH AUTHOR
.nf
This man-page was written by Einar Lueck <elelueck@de.ibm.com>.
.fi