aoeping.8 4.1 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149
  1. .TH aoeping 8
  2. .SH NAME
  3. aoeping \- simple communication with AoE device
  4. .SH SYNOPSIS
  5. .nf
  6. .B aoeping [options] {shelf} {slot} {netif}
  7. .fi
  8. .SH DESCRIPTION
  9. The
  10. .I aoeping
  11. program performs simple one or two-round-trip communication with an
  12. ATA over Ethernet (AoE) device.
  13. .PP
  14. Running \fBaoeping\fP without command line arguments will result in a
  15. short usage summary being displayed.
  16. .PP
  17. The \fBaoeping\fP program will wait forever if if doesn't receive
  18. an expected response. The caller should use a time out to catch
  19. this situation.
  20. .SS Arguments
  21. .TP
  22. \fBshelf\fP
  23. This should be the shelf address (major AoE address) of the AoE device
  24. to communicate with.
  25. .TP
  26. \fBslot\fP
  27. This should be the slot address (minor AoE address) of the AoE device
  28. to communicate with.
  29. .TP
  30. \fBnetif\fP
  31. The name of the ethernet network interface to use for AoE
  32. communications, e.g., eth1.
  33. .SS Options
  34. .TP
  35. \fB-i\fP
  36. Issue an ATA "identify device" command after receiving the AoE
  37. device's Config
  38. Query response. The "ident" response will be printed on standard
  39. output as a hexidecimal dump.
  40. .TP
  41. \fB-v\fP
  42. Turn on
  43. more copious output, including a hexidecimal dump of the Config Query
  44. response from the AoE device (see AoE spec at URL below).
  45. .TP
  46. \fB-s\fP
  47. This option takes an argument. The
  48. argument is a decimal integer that specifies the number of seconds
  49. that \fBaoeping\fP will wait for a response before timing out and
  50. exiting with a non-zero status.
  51. .TP
  52. \fB-S\fP
  53. This option takes an argument. The
  54. argument is the name of a SMART command to send to the disk. The
  55. SMART commands in the list below are supported. If the command
  56. requires data
  57. transfer, one sector (512 bytes) of data is always the amount
  58. transfered. If the command takes a parameter (for the Low LBA
  59. register), then the name of the SMART command is immediately followed
  60. by a colon and then a number, the value of the parameter, e.g., "-S
  61. read_log:1".
  62. .IP
  63. read_data
  64. offline_immediate
  65. read_log
  66. write_log
  67. enable
  68. disable
  69. return_status
  70. For \fBwrite_log\fP, \fBaoeping\fP reads from
  71. standard input the one sector of data to be
  72. written to the specified log.
  73. The aoeping command just sends and receives SMART commands, without
  74. interpreting them. See the ATA specification for more information on
  75. using SMART.
  76. .LP
  77. .TP
  78. \fB-t\fP
  79. (This is an advanced feature.) This option has an argument. The
  80. argument is a decimal integer that is used as the initial tag, with
  81. the highest bit set, as
  82. the
  83. first tag in ATA commands. Tags for subsequent ATA commands will be
  84. incremented by one.
  85. .TP
  86. \fB-h\fP
  87. Show a usage summary.
  88. .SH EXAMPLE
  89. In this example, the root user
  90. uses \fBaoeping\fP to check for the presence of aoe device e10.9 on
  91. network interface eth0.
  92. .IP
  93. .EX
  94. bash# aoeping -v 10 9 eth0 | head
  95. tag: 80000000
  96. eth: eth0
  97. shelf: 10
  98. slot: 9
  99. config query response:
  100. 00 0d 87 aa c9 00 00 10 04 00 11 1f 88 a2 18 00
  101. 00 0a 09 01 00 00 00 00 00 03 30 08 00 10 00 04
  102. 66 6f 6f 0a 00 ff ff ff ff ff ff ff ff ff ff ff
  103. ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff
  104. ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff
  105. .EE
  106. .LP
  107. The next example shows root making sure the disk on the e10.9 is still
  108. responsive by issuing an ATA device identify command with a 20-second
  109. timeout.
  110. .IP
  111. .EX
  112. bash# aoeping -i -s 20 \\
  113. 10 9 eth0 > /dev/null \\
  114. && echo ok
  115. ok
  116. .EE
  117. .LP
  118. The next example uses SMART to determine whether the disk on e10.9
  119. thinks it
  120. has exceeded its error threshold. The ATA spec says that the LBA Mid
  121. register will be 0x4f when the disk has not exceeded its error
  122. threshold.
  123. .IP
  124. .EX
  125. bash# aoeping -S return_status \\
  126. 10 9 eth0 | grep 'LBA Mid: 0x4f' \\
  127. > /dev/null \\
  128. && echo ok
  129. ok
  130. .EE
  131. .LP
  132. Note that in a script, it would be prudent to specify and handle a
  133. timeout. Also, a good script would make sure the
  134. \fBStatus\fP register does not have the error bit (bit zero) or the
  135. device fault bit (bit 5) set.
  136. .SH "SEE ALSO"
  137. .IR aoe-discover (8),
  138. .IR aoe-interfaces (8),
  139. .IR aoe-mkdevs (8),
  140. .IR aoe-mkshelf (8),
  141. .IR aoe-stat (8),
  142. \fIAoE (ATA over Ethernet)\fP: http://www.coraid.com/documents/AoEr8.txt,
  143. \fIATA specification\fP
  144. .SH AUTHOR
  145. Ed L. Cashin (ecashin@coraid.com)