man/lldpctl.8

   1 .\" Copyright (c) 2006 Pierre-Yves Ritschard <pyr@openbsd.org>
   2 .\" Copyright (c) 2008 Vincent Bernat <bernat@luffy.cx>
   3 .\"
   4 .\" Permission to use, copy, modify, and/or distribute this software for any
   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: July 16 2008 $
  17 .Dt LLDPCTL 8
  18 .Os
  19 .Sh NAME
  20 .Nm lldpctl
  21 .Nd control LLDP daemon
  22 .Sh SYNOPSIS
  23 .Nm
  24 .Op Fl adv
  25 .Op Fl L Ar location
  26 .Op Fl P Ar policy
  27 .Op Fl O Ar poe
  28 .Op Fl o Ar poe
  29 .Op Ar interface ...
  30 .Sh DESCRIPTION
  31 The
  32 .Nm
  33 program controls
  34 .Xr lldpd 8
  35 daemon.
  36 .Pp
  37 When no specific option is given,
  38 .Nm
  39 displays the list of discovered neighbors along with
  40 some of their advertised capabilities. If some interfaces are given,
  41 only those interfaces will be displayed.
  42 .Pp
  43 The options are as follows:
  44 .Bl -tag -width Ds
  45 .It Fl d
  46 Enable more debugging information.
  47 .It Fl v
  48 Show
  49 .Nm
  50 version.
  51 .It Fl a
  52 Display all remote ports, including those hidden by the smart filter.
  53 .It Fl f Ar format
  54 Choose the output format. Currently
  55 .Em plain ,
  56 .Em xml
  57 and
  58 .Em keyvalue
  59 formats are available. The default is
  60 .Em plain.
  61 .It Fl L Ar location
  62 Enable the transmission of LLDP-MED location TLV for the given
  63 interfaces. This option can be repeated several times to enable the
  64 transmission of the location in several formats. Several formats are
  65 accepted:
  66 .Bl -tag -width "XX"
  67 .It Em Coordinate based location
  68 The format of
  69 .Ar location
  70 is
  71 .Ar 1:48.85667N:2.2014E:117.47:m:1
  72 The first digit is always
  73 .Ar 1 .
  74 It is followed by the latitude, a letter for the direction (
  75 .Ar E
  76 or
  77 .Ar W
  78 for East or West), the longitude and a letter for the direction (
  79 .Ar N
  80 or
  81 .Ar S
  82 ). The next figure is the altitude. It can be expressed in meters (the
  83 next letter is then
  84 .Ar m
  85 ) or in floors (the letter should be
  86 .Ar f
  87 ). The last digit is the datum. It can either be
  88 .Ar 1
  89 (WGS84),
  90 .Ar 2
  91 (NAD83) or
  92 .Ar 3
  93 (NAD83/MLLW).
  94 .It Em Civic address
  95 The location can be expressed as an address. The format of the
  96 location is then
  97 .Ar 2:FR:6:Commercial Rd:3:Roseville:19:4
  98 The first digit is always
  99 .Ar 2 .
 100 The next two letters are the country code. Then, arguments are paired
 101 to form the address. The first member of the pair is a digit
 102 indicating the type of the second member. Here is the list of
 103 valid types:
 104 .Bl -tag -width "XXXX." -compact
 105 .It Sy 0
 106 Language
 107 .It Sy 1
 108 National subdivisions
 109 .It Sy 2
 110 County, parish, district
 111 .It Sy 3
 112 City, township
 113 .It Sy 4
 114 City division, borough, ward
 115 .It Sy 5
 116 Neighborhood, block
 117 .It Sy 6
 118 Street
 119 .It Sy 16
 120 Leading street direction
 121 .It Sy 17
 122 Trailing street suffix
 123 .It Sy 18
 124 Street suffix
 125 .It Sy 19
 126 House number
 127 .It Sy 20
 128 House number suffix
 129 .It Sy 21
 130 Landmark or vanity address
 131 .It Sy 22
 132 Additional location info
 133 .It Sy 23
 134 Name
 135 .It Sy 24
 136 Postal/ZIP code
 137 .It Sy 25
 138 Building
 139 .It Sy 26
 140 Unit
 141 .It Sy 27
 142 Floor
 143 .It Sy 28
 144 Room number
 145 .It Sy 29
 146 Place type
 147 .It Sy 128
 148 Script
 149 .El
 150 .It ECS ELIN
 151 This is a numerical string using for setting up emergency call. The
 152 format of the location is then the following:
 153 .Ar 3:0000000911
 154 where the first digit should be
 155 .Ar 3
 156 and the second argument is the ELIN number.
 157 .El
 158 .Pp
 159 When setting a location for a given port, all previous locations are
 160 erased. To erase all location, just use the empty string. There is
 161 currently no way to get the location from the command line.
 162 .Pp
 163 .It Fl P Ar policy
 164 Enable the transmission of LLDP-MED Network Policy TLVs for the given
 165 interfaces. This option can be repeated several times to specify
 166 different policies. Format (without spaces!):
 167 .Pp
 168 .Em App-Type
 169 :
 170 .Ar U
 171 :
 172 .Ar T
 173 :
 174 .Ar VLAN-ID
 175 :
 176 .Ar L2-Prio
 177 :
 178 .Ar DSCP
 179 .Bl -tag -width "XX"
 180 .It Ar App-Type
 181 Valid application types (see ANSI/TIA-1057 table 12):
 182 .Bl -tag -width "X." -compact
 183 .It Sy 1
 184 Voice
 185 .It Sy 2
 186 Voice Signaling
 187 .It Sy 3
 188 Guest Voice
 189 .It Sy 4
 190 Guest Voice Signaling
 191 .It Sy 5
 192 Softphone Voice
 193 .It Sy 6
 194 Video Conferencing
 195 .It Sy 7
 196 Streaming Video
 197 .It Sy 8
 198 Video Signaling
 199 .El
 200 .It Ar U
 201 Unknown Policy Flag.
 202 .Bl -tag -width "X." -compact
 203 .It Sy 0
 204 Network policy for the specified application type is defined.
 205 .It Sy 1
 206 Network policy for the specified application type is required by
 207 the device but is currently unknown. This is used by Endpoint
 208 Devices, not by Network Connectivity Devices.
 209 .El
 210 .It Ar T
 211 Tagged Flag.
 212 .Bl -tag -width "X." -compact
 213 .It Sy 0
 214 Untagged VLAN. In this case the VLAN ID and the Layer 2 Priority
 215 are ignored and only the DSCP value has relevance.
 216 .It Sy 1
 217 Tagged VLAN.
 218 .El
 219 .It Ar VLAN-ID
 220 IEEE 802.1q VLAN ID (VID). A value of 1 through 4094 defines a
 221 VLAN ID. A value of 0 means that only the priority level is
 222 significant.
 223 .It Ar L2-Prio
 224 IEEE 802.1d / IEEE 802.1p Layer 2 Priority, also known as Class of Service
 225 (CoS), to be used for the specified application type.
 226 .Bl -tag -width "X." -compact
 227 .It Sy 1
 228 Background
 229 .It Sy 2
 230 Spare
 231 .It Sy 0
 232 Best Effort (default)
 233 .It Sy 3
 234 Excellent Effort
 235 .It Sy 4
 236 Controlled Load
 237 .It Sy 5
 238 Video
 239 .It Sy 6
 240 Voice
 241 .It Sy 7
 242 Network Control
 243 .El
 244 .It Ar DSCP
 245 DiffServ/Differentiated Services Code Point (DSCP) value as defined
 246 in IETF RFC 2474 for the specified application type. Value: 0 (default
 247 per RFC 2475) through 63. Note: The class selector DSCP values are
 248 backwards compatible for devices that only support the old IP
 249 precedence Type of Service (ToS) format. (See the RFCs for what
 250 these values mean.)
 251 .It Examples:
 252 .Bl -tag -width "X." -compact
 253 .It Sy 1:0:1:500:6:46
 254 Voice (1): not unknown (0), tagged (1), VLAN-ID 500, l2 prio Voice (6), DSCP 46 (EF, Expedited Forwarding)
 255 .It Sy 2:0:1:500:3:24
 256 Voice Signaling (2): not unknown (0), tagged (1), VLAN-ID 500, l2 prio
 257 Excellent Effort (3), DSCP 24 (CS3, Class Selector 3)
 258 .El
 259 .El
 260 .Pp
 261 .It Fl O Ar poe
 262 Enable the transmission of LLDP-MED POE-MDI TLV for the given
 263 interfaces. One can act as a PD (power consumer) or a PSE (power
 264 provider). No check is done on the validity of the parameters while
 265 LLDP-MED requires some restrictions:
 266 .Bl -bullet
 267 .It
 268 PD shall never request more power than physical 802.3af class.
 269 .It
 270 PD shall never draw more than the maximum power advertised by PSE.
 271 .It
 272 PSE shall not reduce power allocated to PD when this power is in use.
 273 .It
 274 PSE may request reduced power using conservation mode
 275 .It
 276 Being PSE or PD is a global paremeter, not a per-port parameter.
 277 .Nm
 278 does not enforce this: a port can be set as PD or PSE. LLDP-MED also
 279 requires for a PSE to only have one power source (primary or
 280 backup). Again,
 281 .Nm
 282 does not enforce this. Each port can have its own power source. The
 283 same applies for PD and power priority. LLDP-MED MIB does not allow
 284 this kind of representation.
 285 .El
 286 .Pp
 287 This option is distinct of
 288 .Fl o
 289 option. You may want to use both options at the same time.
 290 .Pp
 291 The format of this option is (without spaces):
 292 .Pp
 293 .Em type
 294 :
 295 .Ar source
 296 :
 297 .Ar priority
 298 :
 299 .Ar value
 300 .Bl -tag -width "XX"
 301 .It Ar type
 302 Valid types are:
 303 .Bl -tag -width "XXX." -compact
 304 .It Sy PSE
 305 Power Sourcing Entity (power provider)
 306 .It Sy PD
 307 Power Device (power consumer)
 308 .El
 309 .It Ar source
 310 Valid sources are:
 311 .Bl -tag -width "X." -compact
 312 .It Sy unknown
 313 Unknown
 314 .It Sy primary
 315 For PSE, the power source is the primary power source.
 316 .It Sy backup
 317 For PSE, the power source is the backup power source or a power
 318 conservation mode is asked (the PSE may be running on UPS for
 319 example).
 320 .It Sy pse
 321 For PD, the power source is the PSE.
 322 .It Sy local
 323 For PD, the power source is a local source.
 324 .It Sy both
 325 For PD, the power source is both the PSE and a local source.
 326 .El
 327 .It Ar priority
 328 Four priorities are available:
 329 .Bl -tag -width "X." -compact
 330 .It Sy unknown
 331 Unknown priority
 332 .It Sy critical
 333 Critical
 334 .It Sy high
 335 High
 336 .It Sy low
 337 Low
 338 .El
 339 .It Ar value
 340 For PD, the power value is the total power in milliwatts required
 341 by a PD device from the PSE device.
 342 .El
 343 .It Fl o Ar poe
 344 Enable the transmission of Dot3 POE-MDI TLV for the given
 345 interfaces. One can act as a PD (power consumer) or a PSE (power
 346 provider). This option is distinct of the
 347 .Fl O
 348 option. You might want to use both. Contrary to LLDP-MED POE-MDI TLV,
 349 Dot3 POE-MDI TLV are strictly per-port values.
 350 .Pp
 351 The format of this option is (without spaces):
 352 .Pp
 353 .Em type
 354 :
 355 .Ar supported
 356 :
 357 .Ar enabled
 358 :
 359 .Ar paircontrol
 360 :
 361 .Ar powerpairs
 362 :
 363 .Ar class
 364 [ :
 365 .Ar powertype
 366 :
 367 .Ar source
 368 :
 369 .Ar priority
 370 :
 371 .Ar requested
 372 :
 373 .Ar allocated
 374 ]
 375 .Bl -tag -width "XX"
 376 .It Ar type
 377 Valid types are:
 378 .Bl -tag -width "XXX." -compact
 379 .It Sy PSE
 380 Power Sourcing Entity (power provider)
 381 .It Sy PD
 382 Power Device (power consumer)
 383 .El
 384 .It Ar powerpairs
 385 Valid values are:
 386 .Bl -tag -width "X." -compact
 387 .It Sy signal
 388 The signal pairs only are in use.
 389 .It Sy spare
 390 The spare pairs only are in use.
 391 .El
 392 .It Ar class
 393 Five classes are available:
 394 .Bl -tag -width "X." -compact
 395 .It Sy 1
 396 class 0
 397 .It Sy 2
 398 class 1
 399 .It Sy 3
 400 class 2
 401 .It Sy 4
 402 class 3
 403 .It Sy 5
 404 class 4
 405 .It Sy 0
 406 no class
 407 .El
 408 .El
 409 .Pp
 410 .Ar supported ,
 411 .Ar enabled
 412 and
 413 .Ar paircontrol
 414 can be set to to 0 or 1.
 415 .Ar supported
 416 means that MDI power is supported on the given port.
 417 .Ar enabled
 418 means that MDI power is enabled on the given port.
 419 .Ar paircontrol
 420 is used to indicate if the pair selection can be controlled on the
 421 given port.
 422 .Pp
 423 .Ar powertype ,
 424 .Ar source ,
 425 .Ar priority
 426 (and remaining values) are optional. They are only requested in
 427 conformance with 802.3at.
 428 .Ar type
 429 should be either 1 or 2. For source, use one of the following values:
 430 Valid sources are:
 431 .Bl -tag -width "X." -compact
 432 .It Sy 0
 433 Unknown
 434 .It Sy 1
 435 For PD, the power source is the PSE. For PSE, the power source is the
 436 primary power source.
 437 .It Sy 2
 438 For PD, the power source is a local source. For PSE, the power source
 439 is the backup power source or a power conservation mode is asked (the
 440 PSE may be running on UPS for example).
 441 .It Sy 3
 442 For PD, the power source is both the PSE and a local source. For PSE,
 443 this value should not be used.
 444 .El
 445 For
 446 .Ar priority ,
 447 see what is done for LLDP-MED MDI/POE.
 448 .Ar requested
 449 and
 450 .Ar allocated
 451 are respectively the PD requested power value and the PSE allocated
 452 power value. This should be expressed in milliwatts.
 453 .El
 454 .Sh FILES
 455 .Bl -tag -width "/var/run/lldpd.socketXX" -compact
 456 .It /var/run/lldpd.socket
 457 Unix-domain socket used for communication with
 458 .Xr lldpd 8 .
 459 .El
 460 .Sh SEE ALSO
 461 .Xr lldpd 8
 462 .Sh AUTHORS
 463 .An -nosplit
 464 The
 465 .Nm
 466 program was written by
 467 .An Vincent Bernat Aq bernat@luffy.cx .