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