]>
Commit | Line | Data |
---|---|---|
43c02e7b VB |
1 | .\" Copyright (c) 2006 Pierre-Yves Ritschard <pyr@openbsd.org> |
2 | .\" Copyright (c) 2008 Vincent Bernat <bernat@luffy.cx> | |
3 | .\" | |
51434125 | 4 | .\" Permission to use, copy, modify, and/or distribute this software for any |
43c02e7b VB |
5 | .\" purpose with or without fee is hereby granted, provided that the above |
6 | .\" copyright notice and this permission notice appear in all copies. | |
7 | .\" | |
8 | .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES | |
9 | .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF | |
10 | .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR | |
11 | .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES | |
12 | .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN | |
13 | .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF | |
14 | .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. | |
15 | .\" | |
16 | .Dd $Mdocdate: August 21 2008 $ | |
17 | .Dt LLDPD 8 | |
18 | .Os | |
19 | .Sh NAME | |
20 | .Nm lldpd | |
21 | .Nd LLDP daemon | |
22 | .Sh SYNOPSIS | |
23 | .Nm | |
96e49a40 | 24 | .Op Fl dxcseiklrv |
9e5d99d4 | 25 | .Op Fl D Ar debug |
7b6cbfe2 | 26 | .Op Fl p Ar pidfile |
0765b92d | 27 | .Op Fl S Ar description |
d4afb919 | 28 | .Op Fl P Ar platform |
740d517e | 29 | .Op Fl X Ar socket |
43c02e7b | 30 | .Op Fl m Ar management |
0262adbb | 31 | .Op Fl u Ar file |
ba85f9f4 | 32 | .Op Fl I Ar interfaces |
5339e725 | 33 | .Op Fl C Ar interfaces |
89840df0 | 34 | .Op Fl M Ar class |
42b39485 | 35 | .Op Fl H Ar hide |
51534ef3 | 36 | .Op Fl L Ar lldpcli |
94f6ce25 | 37 | .Op Fl O Ar configfile |
43c02e7b VB |
38 | .Sh DESCRIPTION |
39 | .Nm | |
40 | is a daemon able to receive and send | |
41 | .Em LLDP | |
42 | frames. The Link Layer Discovery Protocol is a vendor-neutral Layer 2 | |
43 | protocol that allows a network device to advertise its identity and | |
44 | capabilities on the local network. | |
45 | .Pp | |
46 | .Nm | |
47 | also implements an SNMP subagent using AgentX protocol to interface to | |
48 | a regular SNMP agent like Net-SNMP. To enable this subagent, you need | |
49 | something like that in your | |
50 | .Xr snmpd.conf 5 : | |
51 | .Bd -literal -offset indent | |
52 | master agentx | |
53 | .Ed | |
54 | .Pp | |
55 | This daemon implements both reception and sending. It will collect | |
56 | various information to send LLDP frames to all Ethernet interfaces, | |
57 | including management address, speed and VLAN names. | |
58 | .Pp | |
59 | The options are as follows: | |
60 | .Bl -tag -width Ds | |
61 | .It Fl d | |
62 | Do not daemonize. | |
63 | If this option is specified, | |
64 | .Nm | |
9856f279 | 65 | will run in the foreground. When specified one more time, |
d90db09b VB |
66 | .Nm |
67 | will not log to syslog but only to stderr. Then, this option can be | |
68 | specified many times to increase verbosity. When specified four times, | |
69 | debug logs will be enabled. They can be filtered with | |
9e5d99d4 VB |
70 | .Fl D |
71 | flag. | |
72 | .It Fl D Ar debug | |
73 | This option allows the user to filter out debugging information by | |
74 | specifying allowed tokens. This option can be repeated several times | |
75 | to allow several tokens. This option must be combined with the | |
76 | .Fl d | |
77 | flag to have some effect. Only debugging logs can be filtered. Here is | |
78 | a list of allowed tokens with their description: | |
79 | .Bl -tag -width "XXXXXXXXXX" -offset "XXXX" -compact | |
80 | .It Sy main | |
81 | Main daemon. | |
82 | .It Sy interfaces | |
83 | Discovery of local interfaces. | |
84 | .It Sy lldp | |
85 | LLDP PDU encoding/decoding. | |
86 | .It Sy edp | |
87 | EDP PDU encoding/decoding. | |
88 | .It Sy cdp | |
89 | CDP/FDP PDU encoding/decoding. | |
90 | .It Sy sonmp | |
91 | SONMP PDU encoding/decoding. | |
92 | .It Sy event | |
93 | Events management. | |
94 | .It Sy libevent | |
95 | Events management but for logs generated by libevent. | |
96 | .It Sy privsep | |
97 | Privilege separation. | |
98 | .It Sy localchassis | |
99 | Retrieval of information related to the local chassis. | |
100 | .It Sy rpc | |
101 | Client communication. | |
102 | .It Sy control | |
103 | Management of the Unix control socket. | |
104 | .It Sy snmp | |
105 | SNMP subagent. | |
106 | .It Sy libsnmp | |
107 | SNMP subagent but for logs generated by NetSNMP. | |
108 | .It Sy decode | |
109 | Generic PDU decoding. | |
110 | .It Sy marshal | |
111 | Low-level serialization mechanisms. | |
112 | .It Sy alloc | |
113 | Low-level allocation mechanisms. | |
114 | .It Sy send | |
115 | Sending PDU to some interface. | |
116 | .It Sy receive | |
117 | Receiving PDU from some interface. | |
118 | .It Sy loop | |
119 | Main loop. | |
120 | .It Sy smartfilter | |
121 | Smart filtering of different protocols on the same port. | |
e12c2365 VB |
122 | .It Sy netlink |
123 | Netlink subsystem. | |
9e5d99d4 | 124 | .El |
7b6cbfe2 VB |
125 | .It Fl p Ar pidfile |
126 | Use the provided PID file to record | |
127 | .Nm | |
128 | PID instead of @LLDPD_PID_FILE@. | |
de1b1b3a VB |
129 | .It Fl k |
130 | Disable advertising of kernel release, version and machine. Kernel name | |
131 | (ie: Linux) will still be shared, and Inventory software version will be set | |
132 | to 'Unknown'. | |
0765b92d VB |
133 | .It Fl S Ar description |
134 | Override system description with the provided description. The default | |
135 | description is the kernel name, the node name, the kernel version, the | |
136 | build date and the architecture (except if you use the | |
137 | .Fl k | |
138 | flag described above). | |
d4afb919 VB |
139 | .It Fl P Ar platform |
140 | Override the CDP platform name with the provided value. The default | |
141 | description is the kernel name (Linux). | |
43c02e7b | 142 | .It Fl x |
740d517e | 143 | Enable SNMP subagent. |
43c02e7b VB |
144 | With this option, |
145 | .Nm | |
21d89e7d VB |
146 | will enable an SNMP subagent using AgentX protocol. This allows you to |
147 | get information about local system and remote systems through SNMP. | |
740d517e V |
148 | .It Fl X Ar socket |
149 | Enable SNMP subagent using the specified socket. | |
150 | .Nm | |
151 | will enable an SNMP subagent using AgentX protocol for the given | |
152 | socket. This option implies the previous one. The default socket is | |
efc68c65 | 153 | usually |
740d517e V |
154 | .Em /var/agentx/master . |
155 | You can specify a socket like | |
156 | .Em tcp:127.0.0.1:705 | |
157 | for example. Since the process that will open this socket is enclosed | |
158 | in a chroot, you need to specify an IP address (not a hostname) when | |
159 | using a TCP or UDP socket. | |
43c02e7b VB |
160 | .It Fl c |
161 | Enable the support of CDP protocol to deal with Cisco routers that do | |
0c877af0 | 162 | not speak LLDP. If repeated, CDPv1 packets will be sent even when |
43d10956 | 163 | there is no CDP peer detected. If repeated once again, CDPv2 packets |
368daef3 VB |
164 | will be sent even when there is no CDP peer detected. If repeated once |
165 | again (i.e. | |
166 | .Fl cccc ) , | |
167 | CDPv1 will be disabled and CDPv2 will be enabled. If repeated once | |
168 | again (i.e. | |
169 | .Fl ccccc ) , | |
170 | CDPv1 will be disabled and CDPv2 will be forced. | |
031118c4 VB |
171 | .It Fl f |
172 | Enable the support of FDP protocol to deal with Foundry routers that do | |
0c877af0 VB |
173 | not speak LLDP. If repeated, FDP packets will be sent even when there |
174 | is no FDP peer detected. | |
43c02e7b VB |
175 | .It Fl s |
176 | Enable the support of SONMP protocol to deal with Nortel routers and | |
0c877af0 VB |
177 | switches that do not speak LLDP. If repeated, SONMP packets will be |
178 | sent even when there is no SONMP peer detected. | |
43c02e7b VB |
179 | .It Fl e |
180 | Enable the support of EDP protocol to deal with Extreme routers and | |
0c877af0 VB |
181 | switches that do not speak LLDP. If repeated, EDP packets will be sent |
182 | even when there is no EDP peer detected. | |
183 | .It Fl l | |
184 | Force to send LLDP packets even when there is no LLDP peer detected | |
185 | but there is a peer speaking another protocol detected. By default, | |
186 | LLDP packets are sent when there is a peer speaking LLDP detected or | |
46baf627 | 187 | when there is no peer at all. If repeated, LLDP is disabled. |
537a8043 VB |
188 | .It Fl r |
189 | Receive-only mode. With this switch, | |
190 | .Nm | |
191 | will not send any frame. It will only listen to neighbors. | |
43c02e7b | 192 | .It Fl m Ar management |
d4e4c804 VB |
193 | Specify the management addresses of this system. As for interfaces |
194 | (described below), this option can use wildcards and inversions. | |
abfea7d0 VB |
195 | Without this option, the first IPv4 and the first IPv6 are used. If an |
196 | exact IP address is provided, it is used as a management address | |
197 | without any check. If only negative patterns are provided, only one | |
198 | IPv4 and one IPv6 addresses are chosen. Otherwise, many of them can be | |
199 | selected. If you want to blacklist IPv6 addresses, you can use | |
d4e4c804 | 200 | .Em !*:* . |
68bc4a4d VB |
201 | If an interface name is matched, the first IPv4 address and the first |
202 | IPv6 address associated to this interface will be chosen. | |
0262adbb ZM |
203 | .It Fl u Ar file |
204 | Specify the Unix-domain socket used for communication with | |
205 | .Xr lldpctl 8 . | |
ba85f9f4 | 206 | .It Fl I Ar interfaces |
5a1f4586 VB |
207 | Specify which interface to listen and send LLDPDU to. Without this |
208 | option, | |
ba85f9f4 | 209 | .Nm |
5a1f4586 | 210 | will use all available physical interfaces. This option can use |
ba85f9f4 | 211 | wildcards. Several interfaces can be specified separated by commas. |
5abfffc2 | 212 | It is also possible to blacklist an interface by suffixing it with an |
8b53fc2c VB |
213 | exclamation mark. It is possible to whitelist an interface by |
214 | suffixing it with two exclamation marks. A whitelisted interface beats | |
cc351810 | 215 | a blacklisted interface which beats a simple matched interface. For |
8b53fc2c | 216 | example, with |
5abfffc2 VB |
217 | .Em eth*,!eth1,!eth2 |
218 | .Nm | |
5a1f4586 | 219 | will only use interfaces starting by |
5abfffc2 VB |
220 | .Em eth |
221 | with the exception of | |
222 | .Em eth1 | |
223 | and | |
224 | .Em eth2 . | |
8b53fc2c VB |
225 | While with |
226 | .Em *,!eth*,!!eth1 | |
227 | .Nm | |
5a1f4586 | 228 | will use all interfaces, except interfaces starting by |
8b53fc2c VB |
229 | .Em eth |
230 | with the exception of | |
231 | .Em eth1 . | |
627e31c4 VB |
232 | When an exact match is found, it will circumvent some tests. For example, if |
233 | .Em eth0.12 | |
234 | is specified, it will be accepted even if this is a VLAN interface. | |
5339e725 VB |
235 | .It Fl C Ar interfaces |
236 | Specify which interfaces to use for computing chassis ID. Without this | |
237 | option, all interfaces are considered. | |
238 | .Nm | |
239 | will take the first MAC address from all the considered interfaces | |
240 | to compute the chassis ID. The logic of this option is the same as for | |
241 | .Fl I | |
242 | flag: you can exclude interfaces with an exclamation mark and use | |
243 | globbing to specify several interfaces. If all interfaces are | |
244 | blacklisted (with | |
245 | .Em !* ) , | |
246 | the system name is used as a chassis ID instead. | |
89840df0 | 247 | .It Fl M Ar class |
4a1fb0ac VB |
248 | Enable emission of LLDP-MED frame. Depending on the selected class, |
249 | the standard defines which set of TLV should be transmitted. See | |
250 | section 10.2.1. Some devices may be strict about this aspect. The | |
251 | class should be one of the following value: | |
89840df0 | 252 | .Bl -tag -width "0:XX" -compact |
115ff55c | 253 | .It Sy 1 |
89840df0 | 254 | Generic Endpoint (Class I) |
115ff55c | 255 | .It Sy 2 |
4a1fb0ac VB |
256 | Media Endpoint (Class II). In this case, the standard requires to |
257 | define at least one network policy through | |
258 | .Nm lldpcli . | |
115ff55c | 259 | .It Sy 3 |
4a1fb0ac VB |
260 | Communication Device Endpoints (Class III). In this case, the standard |
261 | requires to define at least one network policy through | |
262 | .Nm lldpcli . | |
115ff55c | 263 | .It Sy 4 |
89840df0 | 264 | Network Connectivity Device |
43c02e7b | 265 | .El |
e809a587 VB |
266 | .It Fl i |
267 | Disable LLDP-MED inventory TLV transmission. | |
268 | .Nm | |
269 | will still receive (and publish using SNMP if enabled) those LLDP-MED | |
270 | TLV but will not send them. Use this option if you don't want to | |
271 | transmit sensible information like serial numbers. | |
42b39485 | 272 | .It Fl H Ar hide |
8482abe9 VB |
273 | Filter neighbors. See section |
274 | .Sx FILTERING NEIGHBORS | |
275 | for details. | |
51534ef3 VB |
276 | .It Fl L Ar lldpcli |
277 | Provide an alternative path to | |
278 | .Nm lldpcli | |
279 | for configuration. If empty, does not use | |
280 | .Nm lldpcli | |
281 | for configuration. | |
94f6ce25 TT |
282 | .It Fl O Ar configfile |
283 | Override default configuration locations processed by | |
284 | .Nm lldpcli | |
285 | at start. If a directory is provided, each file contained in it will be read if ending by | |
286 | .Sy .conf. | |
287 | Order is alphabetical. | |
96e49a40 VB |
288 | .It Fl v |
289 | Show | |
290 | .Nm | |
efa6a7a3 | 291 | version. When repeated, show more build information. |
8482abe9 VB |
292 | .El |
293 | .Sh FILTERING NEIGHBORS | |
42b39485 VB |
294 | In a heterogeneous network, you may see several different hosts on the |
295 | same port, even if there is only one physically plugged to this | |
296 | port. For example, if you have a Nortel switch running LLDP which is | |
297 | plugged to a Cisco switch running CDP and your host is plugged to the | |
298 | Cisco switch, you will see the Nortel switch as well because LLDP | |
299 | frames are forwarded by the Cisco switch. This may not be what you | |
300 | want. The | |
301 | .Fl H Ar hide | |
302 | parameter will allow you to tell | |
303 | .Nm | |
304 | to discard some frames that it receives and to avoid to send some | |
8482abe9 VB |
305 | other frames. |
306 | .Pp | |
307 | Incoming filtering and outgoing filtering are | |
308 | unrelated. Incoming filtering will hide some remote ports to get you a | |
309 | chance to know exactly what equipment is on the other side of the | |
310 | network cable. Outgoing filtering will avoid to use some protocols to | |
311 | avoid flooding your network with a protocol that is not handled by the | |
312 | nearest equipment. Keep in mind that even without filtering, | |
313 | .Nm | |
314 | will speak protocols for which at least one frame has been received | |
315 | and LLDP otherwise (there are other options to change this behaviour, | |
316 | for example | |
317 | .Fl cc , ss , ee , ll | |
318 | and | |
319 | .Fl ff | |
320 | ). | |
321 | .Pp | |
322 | When enabling incoming filtering, | |
323 | .Nm | |
324 | will try to select one protocol and filter out neighbors using other | |
325 | protocols. To select this protocol, the rule is to take the less used | |
326 | protocol. If on one port, you get 12 CDP neighbors and 1 LLDP | |
327 | neighbor, this mean that the remote switch speaks LLDP and does not | |
328 | filter CDP. Therefore, we select LLDP. When enabling outgoing | |
329 | filtering, | |
330 | .Nm | |
331 | will also try to select one protocol and only speaks this | |
332 | protocol. The filtering is done per port. Each port may select a | |
333 | different protocol. | |
334 | .Pp | |
335 | There are two additional criteria when enabling filtering: allowing | |
336 | one or several protocols to be selected (in case of a tie) and | |
337 | allowing one or several neighbors to be selected. Even when allowing | |
338 | several protocols, the rule of selecting the protocols with the less | |
339 | neighbors still apply. If | |
340 | .Nm | |
341 | selects LLDP and CDP, this means they have the same number of | |
342 | neighbors. The selection of the neighbor is random. Incoming filtering | |
343 | will select a set of neighbors to be displayed while outgoing | |
344 | filtering will use the selected set of neighbors to decide which | |
345 | protocols to use: if a selected neighbor speaks LLDP and another one | |
346 | CDP, | |
347 | .Nm | |
348 | will speak both CDP and LLDP on this port. | |
349 | .Pp | |
350 | There are some corner cases. A typical example is a switch speaking | |
351 | two protocols (CDP and LLDP for example). You want to get the | |
352 | information from the best protocol but you want to speak both | |
353 | protocols because some tools use the CDP table and some other the LLDP | |
354 | table. | |
355 | .Pp | |
356 | The table below summarize all accepted values for the | |
357 | .Fl H Ar hide | |
358 | parameter. The default value is | |
359 | .Em 15 | |
360 | which corresponds to the corner case described above. The | |
361 | .Em filter | |
362 | column means that filtering is enabled. The | |
363 | .Em 1proto | |
364 | column tells that only one protocol will be kept. The | |
365 | .Em 1neigh | |
366 | column tells that only one neighbor will be kept. | |
367 | .Pp | |
368 | .Bl -column -compact -offset indent "HXXX" "filterX" "1protoX" "1neighX" "filterX" "1protoX" "1neighX" | |
369 | .It Ta Ta incoming Ta Ta outgoing Ta | |
370 | .It Ta Em filter Ta Em 1proto Ta Em 1neigh Ta Em filter Ta Em 1proto Ta Em 1neigh | |
371 | .It Em 0 Ta Ta Ta Ta Ta Ta | |
372 | .It Em 1 Ta x Ta x Ta Ta x Ta x Ta | |
373 | .It Em 2 Ta x Ta x Ta Ta Ta Ta | |
374 | .It Em 3 Ta Ta Ta Ta x Ta x Ta | |
375 | .It Em 4 Ta x Ta Ta Ta x Ta Ta | |
376 | .It Em 5 Ta x Ta Ta Ta Ta Ta | |
377 | .It Em 6 Ta Ta Ta Ta x Ta Ta | |
378 | .It Em 7 Ta x Ta x Ta x Ta x Ta x Ta | |
379 | .It Em 8 Ta x Ta x Ta x Ta Ta Ta | |
380 | .It Em 9 Ta x Ta Ta x Ta x Ta x Ta | |
381 | .It Em 10 Ta Ta Ta Ta x Ta Ta x | |
382 | .It Em 11 Ta x Ta Ta x Ta Ta Ta | |
383 | .It Em 12 Ta x Ta Ta x Ta x Ta Ta x | |
384 | .It Em 13 Ta x Ta Ta x Ta x Ta Ta | |
385 | .It Em 14 Ta x Ta x Ta Ta x Ta Ta x | |
386 | .It Em 15 Ta x Ta x Ta Ta x Ta Ta | |
387 | .It Em 16 Ta x Ta x Ta x Ta x Ta Ta x | |
388 | .It Em 17 Ta x Ta x Ta x Ta x Ta Ta | |
389 | .It Em 18 Ta x Ta Ta Ta x Ta Ta x | |
390 | .It Em 19 Ta x Ta Ta Ta x Ta x Ta | |
de44f068 | 391 | .El |
43c02e7b | 392 | .Sh FILES |
2cbc9cc5 VB |
393 | .Bl -tag -width "@LLDPD_CTL_SOCKET@XX" -compact |
394 | .It @LLDPD_CTL_SOCKET@ | |
43c02e7b VB |
395 | Unix-domain socket used for communication with |
396 | .Xr lldpctl 8 . | |
29095198 VB |
397 | .It /etc/lldpd.conf |
398 | Configuration file for | |
399 | .Nm . | |
400 | Commands in this files are executed by | |
401 | .Xr lldpcli 8 | |
402 | at start. | |
403 | .It /etc/lldpd.d | |
404 | Directory containing configuration files whose commands are executed | |
405 | by | |
406 | .Xr lldpcli 8 | |
407 | at start. | |
43c02e7b VB |
408 | .El |
409 | .Sh SEE ALSO | |
410 | .Xr lldpctl 8 , | |
29095198 | 411 | .Xr lldpcli 8 , |
43c02e7b VB |
412 | .Xr snmpd 8 |
413 | .Sh HISTORY | |
414 | The | |
415 | .Nm | |
416 | program is inspired from a preliminary work of Reyk Floeter. | |
417 | .Sh AUTHORS | |
418 | .An -nosplit | |
419 | The | |
420 | .Nm | |
421 | program was written by | |
422 | .An Pierre-Yves Ritschard Aq pyr@openbsd.org , | |
423 | and | |
424 | .An Vincent Bernat Aq bernat@luffy.cx . |